docs(onboarding): make deploy/compose the primary onboarding path

[sun-970]

Summary

• README "快速开始" now leads with the deploy/compose container path as the recommended first-run experience (one-shot: generate-env → compose up → register → CLI/MCP usage).
• Bare-metal development path (scripts/dev_up.sh) demoted to a development-only subsection with a clear callout that it is for modifying mem source code, not for first-time users.
• Added a platform-equivalence table for bare-metal infrastructure (PostgreSQL + pgvector, MinIO, Ollama) covering macOS (brew), Ubuntu/Debian, and WSL2 (Ubuntu) — addressing the ops dogfood finding that the previous docs were macOS-brew-leaning with no Linux/WSL equivalents.
• "开发环境" section now explicitly states it is for developing mem itself, with a link to the Compose path for users who just want to run mem.
• All references to RUN_LOCAL.md as the primary setup entry updated to point at the Compose path first.

Closes #109

Test plan

• Verify README renders correctly with the new section ordering (Compose first, bare-metal demoted)
• Verify the platform-equivalence table renders as a proper Markdown table
• Verify internal anchor links (#通过-compose-启动推荐) resolve correctly
• Confirm no bare-metal-first instruction remains in the primary onboarding flow (AC-003)

[waterbro-8]

评审：方向认可，但有 1 处必改错误 + 推荐路径的 2 个"照抄会失败"的缺口

本轮为只读验证评审（由 QoderCN 执行），不构成 approve，也不会合并 —— 按 AGENTS.md 第 6 条，批准需由请求中的 reviewer 人工点下。下面所有结论都标注了实际核查方式。

先说站得住的部分

新写的 Compose 命令序列与 docs/DEPLOYMENT.md:126-136 既有的权威流程一致，不是另起炉灶。逐项实测：

• 锚点可跳（test plan 第 3 条）：用 GitHub 的 markdown 渲染接口实测 ### 通过 Compose 启动（推荐） → 生成 id 通过-compose-启动推荐（全角括号被丢弃、空格转连字符），README 中 3 处引用全部命中。
• 表格渲染正常（test plan 第 2 条）：4 列 × 4 行；`curl -fsSL https://ollama.com/install.sh \| sh` 里的 \| 被表格解析器还原成 |，无残留反斜杠。
• deploy/compose/generate-env.sh 存在且 mode 100755；MEM_REGISTRATION_MODE=first_user、MEM_BIND_ADDRESS=127.0.0.1、MEM_EDGE_PORT=8080 与 compose.yaml:208 的端口映射、compose.yaml:213 的 /healthz healthcheck 都对得上。六服务描述准确（另有 minio-init、migrate 两个一次性任务）。
• 裸机注释"自动拉起 PostgreSQL、MinIO、Worker、memd"与 scripts/dev_up.sh:5-8 逐条一致（确实不含 Redis）。
• pgvector bottle 仅为 PG17/18 编译、dev_up.sh 自动探测 —— 与 docs/RUN_LOCAL.md:28-30 一致。
• export MEM_SERVER 确实被 CLI 识别：server/cmd/mem/config.go:80，优先级低于 --server、高于 ~/.mem/config.yaml。

必改：新增 callout 的方向是反的

## 开发环境 在 README.md:181，### 通过 Compose 启动（推荐） 在 README.md:254 —— 在它下面。所以"只想运行 mem 的用户请使用上方的 [Compose 启动]"指向了不存在的上文。

更根本的是：从上往下读，首次用户先撞见的仍然是 Go 1.25 / protoc / pgvector / Ollama 那张裸机清单，这恰好与本 PR 要满足的 AC-001（README 以容器路径开头）相反。建议把整段 ## 快速开始 提到 ## 开发环境 之前，而不是只补一个方向正确的链接 —— 顺带也把 AC-003 真正做掉。

推荐路径的准确性缺口

mem CLI 从哪来，整段没说。 快速开始里出现 mem auth login / mem put / mem search，但 Compose 路径只构建镜像；宿主机 CLI 需要 make build-mem（Makefile:184，要 Go 1.25），而新增 callout 恰好写着 compose 用户"无需安装任何开发工具"，两者互相矛盾；npm 只发布 mem-mcp（npm/package.json 的 bin 里只有 mem-mcp）；docs/RUN_LOCAL.md 全程用的是 bin/mem --server ...。补一行来源即可：make build-mem，或 docker compose exec memd /usr/local/bin/mem（server 镜像确实装了 /usr/local/bin/mem，见 server/Dockerfile runtime 段）。

mem search "a golden retriever standing on green grass" 在 stock compose 上跑不出来。 deploy/compose/compose.yaml:40 给 worker 的 OLLAMA_BASE_URL 是 http://127.0.0.1:11434，指向 worker 容器自身；backend 网络是 internal: true（compose.yaml:233），没有任何 Ollama 服务或出网 override；MEM_DEFAULT_EMBEDDING 等默认模型全为空（compose.yaml:41）。docs/DEPLOYMENT.md:185-189 自己把这套默认称为 model-free baseline，并说明要另写 site-specific override 才能让 worker 访问宿主 Ollama；docs/RUN_LOCAL.md:59-65 还要求 mem model install qwen3-embedding-0.6b-ollama + profile select local-fast-v2。建议二选一：在 CLI 演示处加限定（上传 / 目录 / 网页浏览开箱可用，自然语言检索需先按 DEPLOYMENT.md 补 worker egress override 并安装模型），或把这几条 AI 演示移出首次上手路径。

"这是经过运维验证的最短路径"声明范围偏大。 #109 中 ops 实测的闭环是 up → 首次注册 → 浏览器建目录；README 现在展示的 CLI + 语义检索链路不在被验证范围内。REQ-001 要的正是"用证据词汇陈述已验证闭环"——验证到哪步就只声明到哪步。AC-002（干净环境跑通并留证据）本 PR 尚未附证据。

平台等价表：REQ-002 的靶心，这里最值得补强

Ubuntu 列少前置，Linux 新手第一步就撞墙。 我在这台 WSL2 Ubuntu 26.04 上实测 apt-cache madison postgresql-17 postgresql-17-pgvector，两个包只有 resolute-pgdg 一个来源 —— 也就是必须先配 PGDG apt 源，且 Ubuntu 主仓库不提供 PG17；命令也漏了 sudo（macOS 列是 keg-only 免 sudo，两列的实际门槛并不等价，而这一列的存在意义就是"等价"）。建议指向 PGDG 的 apt 设置步骤，或直接给那 3 行命令。

WSL2 列只写"同 Ubuntu"太薄。 至少两点是 WSL2 特有的：① 从 Windows 侧浏览器打开 http://localhost:8080 需要 mirrored networking 或 netsh portproxy，因为端口映射绑的是 127.0.0.1；② 前置条件"Docker Engine + Docker Compose v2"在 WSL2 要区分 Docker-in-WSL2 与 Docker Desktop。

小问题（顺手改）

• chmod 600 .env 是装饰性的：generate-env.sh:14 用 umask 077 创建文件，:39 已回显 "wrote .env with mode 0600"。与 DEPLOYMENT.md 保持一致所以留着也无妨，只是标注一下它是冗余步骤。
• 前置条件漏了 openssl（generate-env.sh:10 缺它即 die "openssl is required"）。
• 演示路径用 ~/Photos（macOS 味），Linux/WSL 上通常不存在；仓库自带 scripts/demo_data/images/golden_retriever_grass.jpg，与搜索语句正好对应。
• CHANGELOG 里的 `#109` 在反引号内不会成为链接，issue 收不到引用；改为 (#109)。
• ## 仓库结构 的 text 图仍只列根目录 docker-compose.yml（本地开发基础设施），没有 deploy/；主路径换了之后这里也该出现 deploy/compose/。

流程门槛（交 maintainer 判断，我不代为决定）

• AGENTS.md 第 5 条要求 PR 描述含"completed validation ledger"：4 个 test plan 复选框均未勾。
• 第 6 条要求 CI 通过 + 非作者批准：head d340e5e 的 3 个 check-suite 全是 action_required（fork PR 工作流尚未被批准运行），当前没有任何 check-run；PR 上 0 review、0 评论。
• 第 2 条要求实质性改动在 issue 拿到 status:ready 后实施：docs(onboarding): make deploy/compose the primary onboarding path #109 标签仅 type:feature / priority:p1，requirement record 内 status=needs-design、technicalOwner unassigned（仓库确有 status:ready 标签可用）。docs-only 是否算例外，需要有人明确说一句。

结论

结构重定位是对的、与 DEPLOYMENT.md 的一致性也好，值得往这个方向收。合并前建议至少处理：callout 方向（必改）、CLI 获取途径、compose 上的 AI 检索声明范围、Ubuntu 列的 PGDG 前置。AC-002 的干净环境证据（一次 up --build --wait → 浏览器注册 → 建目录的实测记录）请补在 PR 或 #109 里。

[waterbro-8]

Closing under the fork-workflow decision recorded on 2026-09-03: repository
automation is not being enabled for fork pull requests, so a fork head cannot
carry a CI result, and every acceptance gate in this repository is written
against checks that ran. Nothing in this comment is a judgment that the work is
wrong; where it is right, it is re-landed on an organization branch instead.

#109.

A documentation reordering with no accompanying test, which is not itself a
problem, but it cannot be given a check result from a fork branch. #109 stays
open and needs the same content on an organization branch.

One thing worth carrying over, because it was correct and is easy to lose: this
branch moved deploy/compose ahead of the source-build path in the onboarding
order. #131 already made the same argument for the same reason in its first-run
guidance, so if #109 is re-landed, do it together with #131's text rather than
separately, or the two documents will disagree about which path is primary.

The commits are not lost. A closed fork PR keeps its head ref:

git fetch https://github.com/bytefolk/mem.git refs/pull/148/head:pr-148

Every file in this branch was therefore available to the re-doing work, whether
or not it was used.