diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 052c006..daab6c8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -70,6 +70,40 @@ make docker-logs-frontend
 make docker-logs-gateway
 ```
 
+#### Linux: Docker daemon permission denied
+
+If `make docker-init`, `make docker-start`, or `make docker-stop` fails on Linux with an error like below, your current user likely does not have permission to access the Docker daemon socket:
+
+```text
+unable to get image 'deer-flow-dev-langgraph': permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock
+```
+
+Recommended fix: add your current user to the `docker` group so Docker commands work without `sudo`.
+
+1. Confirm the `docker` group exists:
+   ```bash
+   getent group docker
+   ```
+2. Add your current user to the `docker` group:
+   ```bash
+   sudo usermod -aG docker $USER
+   ```
+3. Apply the new group membership. The most reliable option is to log out completely and then log back in. If you want to refresh the current shell session instead, run:
+   ```bash
+   newgrp docker
+   ```
+4. Verify Docker access:
+   ```bash
+   docker ps
+   ```
+5. Retry the DeerFlow command:
+   ```bash
+   make docker-stop
+   make docker-start
+   ```
+
+If `docker ps` still reports a permission error after `usermod`, fully log out and log back in before retrying.
+
 #### Docker Architecture
 
 ```
@@ -236,9 +270,9 @@ Nginx (port 2026) ← Unified entry point
 cd backend
 uv run pytest
 
-# Frontend tests
+# Frontend checks
 cd frontend
-pnpm test
+pnpm check
 ```
 
 ### PR Regression Checks
diff --git a/README.md b/README.md
index ee04ccd..c52f453 100644
--- a/README.md
+++ b/README.md
@@ -204,6 +204,9 @@ make docker-start   # Start services (auto-detects sandbox mode from config.yaml
 `make docker-start` starts `provisioner` only when `config.yaml` uses provisioner mode (`sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider` with `provisioner_url`).
 Backend processes automatically pick up `config.yaml` changes on the next config access, so model metadata updates do not require a manual restart during development.
 
+> [!TIP]
+> On Linux, if Docker-based commands fail with `permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock`, add your user to the `docker` group and re-login before retrying. See [CONTRIBUTING.md](CONTRIBUTING.md#linux-docker-daemon-permission-denied) for the full fix.
+
 **Production** (builds images locally, mounts runtime config and data):
 
 ```bash
diff --git a/frontend/package.json b/frontend/package.json
index ece0129..e69b949 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -6,7 +6,7 @@
   "scripts": {
     "demo:save": "node scripts/save-demo.js",
     "build": "next build",
-    "check": "next lint && tsc --noEmit",
+    "check": "eslint . --ext .ts,.tsx && tsc --noEmit",
     "dev": "next dev --turbo",
     "lint": "eslint . --ext .ts,.tsx",
     "lint:fix": "eslint . --ext .ts,.tsx --fix",