diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index b7af77d..8ce8b99 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -77,7 +77,7 @@ jobs:
             bun-docs-${{ runner.os }}-
 
       - name: Install docs dependencies
-        run: bun install --frozen-lockfile
+        run: cd docs && bun install --frozen-lockfile
 
       - name: Read VERSION
         id: ver
@@ -87,15 +87,15 @@ jobs:
           echo "version=${base}${{ inputs.version_suffix }}" >> "$GITHUB_OUTPUT"
 
       - name: Build docs site
-        run: bun run build
+        run: cd docs && bun run build
 
       - name: Package docs site
         shell: bash
         run: |
           set -euo pipefail
           ARCHIVE="alchemist-website-${{ steps.ver.outputs.version }}.zip"
-          cd build
-          zip -r "../${ARCHIVE}" .
+          cd docs/build
+          zip -r "../../${ARCHIVE}" .
 
       - name: Upload docs artifact
         uses: actions/upload-artifact@v7
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index eda369c..943f941 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -62,7 +62,7 @@ jobs:
           path: |
             node_modules
             ~/.bun/install/cache
-          key: bun-docs-${{ runner.os }}-${{ hashFiles('bun.lock') }}
+          key: bun-docs-${{ runner.os }}-${{ hashFiles('docs/bun.lock') }}
           restore-keys: |
             bun-docs-${{ runner.os }}-
 
@@ -99,3 +99,4 @@ jobs:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v5
+s: actions/deploy-pages@v5
diff --git a/GEMINI.md b/GEMINI.md
index a0b5790..db8e65f 100644
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -7,7 +7,7 @@ Alchemist is a media transcoding tool designed for simplicity and space-saving.
 - **Purpose:** Automated media transcoding and library management to save storage space.
 - **Backend:** Rust 2024 (Tokio, Axum 0.7, SQLx 0.8 with SQLite).
 - **Frontend:** Astro 5, React 18, Tailwind CSS (embedded in the Rust binary via `rust-embed`).
-- **Documentation:** Docusaurus 3.9 (located in the root `package.json`).
+- **Documentation:** Docusaurus 3.9 (located in `docs/package.json`).
 - **Core Technologies:** FFmpeg (analyzer and executor), SQLite (state management), Argon2 (security).
 
 ## Architecture & Pipeline
diff --git a/bun.lock b/docs/bun.lock
similarity index 100%
rename from bun.lock
rename to docs/bun.lock
diff --git a/docs/api.md b/docs/docs/api.md
similarity index 100%
rename from docs/api.md
rename to docs/docs/api.md
diff --git a/docs/architecture.md b/docs/docs/architecture.md
similarity index 100%
rename from docs/architecture.md
rename to docs/docs/architecture.md
diff --git a/docs/changelog.md b/docs/docs/changelog.md
similarity index 100%
rename from docs/changelog.md
rename to docs/docs/changelog.md
diff --git a/docs/codecs.md b/docs/docs/codecs.md
similarity index 100%
rename from docs/codecs.md
rename to docs/docs/codecs.md
diff --git a/docs/configuration-reference.md b/docs/docs/configuration-reference.md
similarity index 100%
rename from docs/configuration-reference.md
rename to docs/docs/configuration-reference.md
diff --git a/docs/contributing/development.md b/docs/docs/contributing/development.md
similarity index 100%
rename from docs/contributing/development.md
rename to docs/docs/contributing/development.md
diff --git a/docs/contributing/overview.md b/docs/docs/contributing/overview.md
similarity index 100%
rename from docs/contributing/overview.md
rename to docs/docs/contributing/overview.md
diff --git a/docs/database-schema.md b/docs/docs/database-schema.md
similarity index 100%
rename from docs/database-schema.md
rename to docs/docs/database-schema.md
diff --git a/docs/docker.md b/docs/docs/docker.md
similarity index 100%
rename from docs/docker.md
rename to docs/docs/docker.md
diff --git a/docs/engine-modes.md b/docs/docs/engine-modes.md
similarity index 100%
rename from docs/engine-modes.md
rename to docs/docs/engine-modes.md
diff --git a/docs/environment-variables.md b/docs/docs/environment-variables.md
similarity index 100%
rename from docs/environment-variables.md
rename to docs/docs/environment-variables.md
diff --git a/docs/faq.md b/docs/docs/faq.md
similarity index 100%
rename from docs/faq.md
rename to docs/docs/faq.md
diff --git a/docs/first-run.md b/docs/docs/first-run.md
similarity index 100%
rename from docs/first-run.md
rename to docs/docs/first-run.md
diff --git a/docs/gpu-passthrough.md b/docs/docs/gpu-passthrough.md
similarity index 100%
rename from docs/gpu-passthrough.md
rename to docs/docs/gpu-passthrough.md
diff --git a/docs/hardware.md b/docs/docs/hardware.md
similarity index 100%
rename from docs/hardware.md
rename to docs/docs/hardware.md
diff --git a/docs/hardware/amd.md b/docs/docs/hardware/amd.md
similarity index 100%
rename from docs/hardware/amd.md
rename to docs/docs/hardware/amd.md
diff --git a/docs/hardware/apple.md b/docs/docs/hardware/apple.md
similarity index 100%
rename from docs/hardware/apple.md
rename to docs/docs/hardware/apple.md
diff --git a/docs/hardware/cpu.md b/docs/docs/hardware/cpu.md
similarity index 100%
rename from docs/hardware/cpu.md
rename to docs/docs/hardware/cpu.md
diff --git a/docs/hardware/intel.md b/docs/docs/hardware/intel.md
similarity index 100%
rename from docs/hardware/intel.md
rename to docs/docs/hardware/intel.md
diff --git a/docs/hardware/nvidia.md b/docs/docs/hardware/nvidia.md
similarity index 100%
rename from docs/hardware/nvidia.md
rename to docs/docs/hardware/nvidia.md
diff --git a/docs/installation.md b/docs/docs/installation.md
similarity index 100%
rename from docs/installation.md
rename to docs/docs/installation.md
diff --git a/docs/library-doctor.md b/docs/docs/library-doctor.md
similarity index 100%
rename from docs/library-doctor.md
rename to docs/docs/library-doctor.md
diff --git a/docs/library-setup.md b/docs/docs/library-setup.md
similarity index 100%
rename from docs/library-setup.md
rename to docs/docs/library-setup.md
diff --git a/docs/notifications.md b/docs/docs/notifications.md
similarity index 100%
rename from docs/notifications.md
rename to docs/docs/notifications.md
diff --git a/docs/overview.md b/docs/docs/overview.md
similarity index 100%
rename from docs/overview.md
rename to docs/docs/overview.md
diff --git a/docs/profiles.md b/docs/docs/profiles.md
similarity index 100%
rename from docs/profiles.md
rename to docs/docs/profiles.md
diff --git a/docs/quick-start.md b/docs/docs/quick-start.md
similarity index 100%
rename from docs/quick-start.md
rename to docs/docs/quick-start.md
diff --git a/docs/scheduling.md b/docs/docs/scheduling.md
similarity index 100%
rename from docs/scheduling.md
rename to docs/docs/scheduling.md
diff --git a/docs/skip-decisions.md b/docs/docs/skip-decisions.md
similarity index 100%
rename from docs/skip-decisions.md
rename to docs/docs/skip-decisions.md
diff --git a/docs/stream-rules.md b/docs/docs/stream-rules.md
similarity index 100%
rename from docs/stream-rules.md
rename to docs/docs/stream-rules.md
diff --git a/docs/troubleshooting.md b/docs/docs/troubleshooting.md
similarity index 100%
rename from docs/troubleshooting.md
rename to docs/docs/troubleshooting.md
diff --git a/docs/web-interface.md b/docs/docs/web-interface.md
similarity index 100%
rename from docs/web-interface.md
rename to docs/docs/web-interface.md
diff --git a/docusaurus.config.ts b/docs/docusaurus.config.ts
similarity index 99%
rename from docusaurus.config.ts
rename to docs/docusaurus.config.ts
index 5c44a50..07f4154 100644
--- a/docusaurus.config.ts
+++ b/docs/docusaurus.config.ts
@@ -39,7 +39,7 @@ const config: Config = {
         docs: {
           routeBasePath: '/',
           sidebarPath: './sidebars.ts',
-          editUrl: 'https://github.com/bybrooklyn/alchemist/edit/main/website/',
+          editUrl: 'https://github.com/bybrooklyn/alchemist/edit/main/docs/',
         },
         pages: false,
         blog: false,
diff --git a/package.json b/docs/package.json
similarity index 100%
rename from package.json
rename to docs/package.json
diff --git a/sidebars.ts b/docs/sidebars.ts
similarity index 100%
rename from sidebars.ts
rename to docs/sidebars.ts
diff --git a/src/css/custom.css b/docs/src/css/custom.css
similarity index 100%
rename from src/css/custom.css
rename to docs/src/css/custom.css
diff --git a/static/img/README.md b/docs/static/img/README.md
similarity index 100%
rename from static/img/README.md
rename to docs/static/img/README.md
diff --git a/static/img/favicon.ico b/docs/static/img/favicon.ico
similarity index 100%
rename from static/img/favicon.ico
rename to docs/static/img/favicon.ico
diff --git a/tsconfig.json b/docs/tsconfig.json
similarity index 100%
rename from tsconfig.json
rename to docs/tsconfig.json
diff --git a/justfile b/justfile
index 2529272..1fd04bf 100644
--- a/justfile
+++ b/justfile
@@ -35,6 +35,10 @@ run:
 web:
     cd web && bun install --frozen-lockfile && bun run dev
 
+# Start documentation dev server only
+docs:
+    cd docs && bun install --frozen-lockfile && bun run start
+
 # ─────────────────────────────────────────
 # BUILD
 # ─────────────────────────────────────────