diff --git a/CHANGELOG.md b/CHANGELOG.md
index c143e7c..ec8970d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -38,6 +38,12 @@ The project publishes 0.x prerelease versions; a stable release line is not yet
 
 ### Changed
 
+- README onboarding now leads with the `deploy/compose` path as the recommended
+  first-run experience (one-shot: `generate-env` → `compose up` → register →
+  use CLI/MCP). The bare-metal development path (`scripts/dev_up.sh`) is
+  demoted to a development-only subsection, and `docs/RUN_LOCAL.md` adds a
+  platform-equivalence table covering macOS, Ubuntu/Debian and WSL2 (`#109`).
+  `mem doctor` already names `deploy/compose` on a machine with no config.
 - Migrate GitHub repository, Release, issue, badge, and raw-content coordinates
   to the canonical `bytefolk` organization while retaining the published npm
   scope and the existing cache paths.
diff --git a/README.md b/README.md
index 8b333d6..15df72a 100644
--- a/README.md
+++ b/README.md
@@ -230,12 +230,34 @@ mem 的壁垒不是绑定某个更大的模型，而是长期积累的、用户
 
 ## 快速开始
 
-项目仍处于 Phase 1 MVP。当前开发体验：
+项目仍处于 Phase 1 MVP。第一次把 mem 跑起来，走 `deploy/compose`：一条命令拉起
+Web、memd、Worker、PostgreSQL、Redis 和 MinIO。这是文档上的主路径。
+`./scripts/dev_up.sh` 只留给要改 Go / Python / Web 的开发机。
+
+`mem doctor` 在一台还没有配置的机器上也会把你指向这条容器路径，而不是裸机配方。
+
+### 通过 Compose 启动（推荐）
+
+前置条件：Docker Engine 和 Docker Compose v2。命令与
+[生产部署指南](docs/DEPLOYMENT.md) 中的权威序列一致。
 
 ```bash
 git clone https://github.com/bytefolk/mem.git
 cd mem
-./scripts/dev_up.sh
+
+cd deploy/compose
+./generate-env.sh
+chmod 600 .env
+docker compose --env-file .env -f compose.yaml up -d --build --wait
+docker compose --env-file .env -f compose.yaml ps
+curl --fail http://127.0.0.1:8080/healthz
+```
+
+启动完成后，浏览器打开 `http://localhost:8080`，完成首次注册（`first_user`
+模式只允许一个账户），然后用 CLI 或 MCP：
+
+```bash
+export MEM_SERVER=http://localhost:8080
 mem auth login
 mem put ~/Photos --recursive
 # 可选：同步端附带可信的拍摄时间、位置和来源；AI 建议稍后在 Web 中确认
@@ -256,9 +278,25 @@ mem resume photos/import
 mem workspace export --output agent-workspace.membundle
 ```
 
-生产部署同时提供单机 Compose 和多机 Helm 方案，完整的密钥、迁移、高可用、
-备份恢复与升级边界见 [生产部署指南](docs/DEPLOYMENT.md)。默认视觉模型的真实英文/中文边界见
-[自然语言搜图基线](docs/acceptance/VISUAL_SEARCH_BASELINE.md)。
+完整的密钥、迁移、高可用、备份恢复与升级边界见
+[生产部署指南](docs/DEPLOYMENT.md)。默认视觉模型的真实英文/中文边界见
+[自然语言搜图基线](docs/acceptance/VISUAL_SEARCH_BASELINE.md)。多机方案见
+`deploy/helm/mem/`。
+
+### 裸机开发环境（仅限开发）
+
+> 裸机路径面向需要修改 Go / Python / Web 代码的开发场景。首次体验或评估请使用
+> 上方的 Compose 路径。
+
+```bash
+git clone https://github.com/bytefolk/mem.git
+cd mem
+./scripts/dev_up.sh
+mem auth login
+```
+
+完整的裸机依赖、Ollama 配置和 smoke 步骤见 [docs/RUN_LOCAL.md](docs/RUN_LOCAL.md)。
+该文档把 macOS brew 步骤并列了 Ubuntu/Debian 与 WSL2 等价命令。
 
 ---
 
diff --git a/docs/RUN_LOCAL.md b/docs/RUN_LOCAL.md
index 14ad3ce..e127542 100644
--- a/docs/RUN_LOCAL.md
+++ b/docs/RUN_LOCAL.md
@@ -1,10 +1,11 @@
-# 本地运行 mem 全栈（裸机 · 无 Docker）
+# 本地运行 mem 全栈（裸机 · 仅限开发）
 
-本文用于启动完整开发栈和手工 smoke。可重复的单元、Race、PostgreSQL 集成、
-Web 浏览器验收及其通过标准统一见 [TESTING.md](TESTING.md)。
+第一次把 mem 跑起来，请走仓库根 README 和 [DEPLOYMENT.md](DEPLOYMENT.md)
+里的 `deploy/compose` 路径，不要从本文开始。本文只覆盖**没有 Docker、需要改
+源码**的开发机。可重复的单元、Race、PostgreSQL 集成、Web 浏览器验收及其通过
+标准统一见 [TESTING.md](TESTING.md)。
 
-在没有 Docker 的 macOS 开发环境中，整套栈可用**本地进程**拉起，不走
-`docker compose`。
+在没有 Docker 的开发环境中，整套栈可用**本地进程**拉起，不走 `docker compose`。
 一条命令起、一条命令停，运行时数据全部落在 `.dev/`（已 gitignore）。
 
 ```
@@ -20,15 +21,23 @@ Web 浏览器验收及其通过标准统一见 [TESTING.md](TESTING.md)。
 
 ## 一次性准备（首次或换机器时）
 
-1. **依赖二进制**（脚本假设它们已就位）：
-   - PostgreSQL + pgvector（brew，keg-only，无需 sudo）：
+1. **依赖二进制**（脚本假设它们已就位）。平台等价：
+
+   | 依赖 | macOS (brew) | Ubuntu / Debian | WSL2 (Ubuntu) |
+   | --- | --- | --- | --- |
+   | PostgreSQL 17 + pgvector | `brew install postgresql@17 pgvector` | `apt install postgresql-17 postgresql-17-pgvector` | 同 Ubuntu（在 WSL2 Ubuntu 中执行） |
+   | MinIO | `brew install minio minio-mc` | 从 https://min.io/download 下载二进制到 `.dev/bin/` | 同 Ubuntu |
+   | Ollama | `brew install ollama` 或从 https://ollama.com 下载 | `curl -fsSL https://ollama.com/install.sh \| sh` | 同 Ubuntu（GPU 走 Windows 侧驱动） |
+   | Go 1.25 / Node 24 / Python 3.11+ / uv / protoc 34.1 | 用各平台官方安装器，版本钉在 `docs/TESTING.md` | 同左 | 同左 |
+
+   - PostgreSQL + pgvector（macOS：brew，keg-only，无需 sudo）：
      ```bash
      brew install postgresql@17 pgvector
      ```
      > 用 `@17` 而不是 `@16`：brew 的 pgvector bottle 只为 postgresql@17/@18
      > 编译了 `vector.so`，装在 @16 上 `CREATE EXTENSION vector` 会失败。
      > `dev_up.sh` 会自动探测 @17/@18/@16 中带匹配 pgvector 的版本。
-   - MinIO server + mc client。推荐用 brew（dl.min.io 在本网络偶发限流/TLS 断连，
+   - MinIO server + mc client。macOS 推荐用 brew（dl.min.io 在本网络偶发限流/TLS 断连，
      brew 走 ghcr.io 更稳）：
      ```bash
      brew install minio minio-mc