diff --git a/.github/workflows/build_docs.yml b/.github/workflows/docs_build.yml
similarity index 78%
rename from .github/workflows/build_docs.yml
rename to .github/workflows/docs_build.yml
index d8f1a73e44..c99bf81253 100644
--- a/.github/workflows/build_docs.yml
+++ b/.github/workflows/docs_build.yml
@@ -6,10 +6,10 @@ on:
   push:
     branches: [main]
     paths:
-      - "./docs"
+      - "docs/**"
   pull_request:
     paths:
-      - "./docs"
+      - "docs/**"
 
 jobs:
   build:
@@ -22,7 +22,10 @@ jobs:
         with:
           node-version: 20
           cache: yarn # or pnpm / npm
+          cache-dependency-path: docs/yarn.lock
       - name: Install dependencies
         run: yarn install # or pnpm install / npm ci
+        working-directory: docs
       - name: Build with VitePress
         run: yarn build # or pnpm build / npm build
+        working-directory: docs
diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/docs_deploy.yml
similarity index 90%
rename from .github/workflows/deploy_docs.yml
rename to .github/workflows/docs_deploy.yml
index 713cf34c76..39f77947b9 100644
--- a/.github/workflows/deploy_docs.yml
+++ b/.github/workflows/docs_deploy.yml
@@ -8,7 +8,7 @@ on:
   push:
     branches: [main]
     paths:
-      - "./docs"
+      - "docs/**"
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -37,15 +37,18 @@ jobs:
         with:
           node-version: 20
           cache: yarn # or pnpm / npm
+          cache-dependency-path: docs/yarn.lock
       - name: Setup Pages
         uses: actions/configure-pages@v5
       - name: Install dependencies
         run: yarn install # or pnpm install / npm ci
+        working-directory: docs
       - name: Build with VitePress
         run: yarn build # or pnpm build / npm build
+        working-directory: docs
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./.vitepress/dist
+          publish_dir: ./docs/.vitepress/dist
           cname: ev.xyz
diff --git a/.github/workflows/preview_docs.yml b/.github/workflows/docs_preview.yml
similarity index 85%
rename from .github/workflows/preview_docs.yml
rename to .github/workflows/docs_preview.yml
index 5b5489121b..6fda6b3fed 100644
--- a/.github/workflows/preview_docs.yml
+++ b/.github/workflows/docs_preview.yml
@@ -10,7 +10,7 @@ on:
       - synchronize
       - closed
     paths:
-      - "./docs"
+      - "docs/**"
 
 concurrency: preview-${{ github.ref }}
 
@@ -28,17 +28,20 @@ jobs:
         with:
           node-version: 20
           cache: yarn
+          cache-dependency-path: docs/yarn.lock
 
       - name: Install dependencies
         run: yarn install --frozen-lockfile
+        working-directory: docs
 
       - name: Build with Base URL
         run: BASE='/docs-preview/pr-${{ github.event.number }}/' yarn build
+        working-directory: docs
 
       - name: Deploy preview
         uses: rossjrw/pr-preview-action@v1
         with:
-          source-dir: .vitepress/dist
+          source-dir: docs/.vitepress/dist
           deploy-repository: evstack/docs-preview
           token: ${{ secrets.PREVIEW_DEPLOY }}
           preview-branch: main
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index 4633e357e9..539ee92db8 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -23,7 +23,7 @@ This is a **VitePress-based documentation site** for Evolve. Key architectural e
 
 ### Content Organization
 
-```
+```txt
 docs/
 ├── .vitepress/config.ts    # Site configuration, navigation, theme
 ├── blog/                   # Blog posts and announcements
diff --git a/docs/README.md b/docs/README.md
index 2b98a793c7..b35f59c0a5 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,4 +1,4 @@
-[![Deploy](https://github.com/evstack/ev-node/actions/workflows/deploy.yml/badge.svg)](https://github.com/evstack/docs/actions/workflows/deploy.yml)
+[![Deploy](https://github.com/evstack/ev-node/actions/workflows/deploy.yml/badge.svg)](https://github.com/evstack/ev-node/actions/workflows/deploy.yml)
 
 # Evolve Documentation Site