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

[waterbro-8]

What changed

README.md

• New 开始使用 / Getting started section placed above the component map: it
  presents deploy/compose as the primary path (generate-env.sh →
  config --quiet → up -d --build --wait → first-user registration →
  folder creation), matching the canonical sequence in docs/DEPLOYMENT.md.
• 开发环境 is retitled 开发环境（仅开发） and converts the dependency list
  into a pinned table (server/go.mod, worker/uv.lock,
  web/package-lock.json), plus a 依赖服务的平台等价 matrix giving the
  WSL2/Linux equivalent for every Homebrew-leaning step.
• The old 快速开始 section is retitled CLI 闭环示例 and now assumes a
  running instance instead of implying scripts/dev_up.sh is the entry point.
  The bare-metal path is preserved, not deleted.
• Documented explicitly what the container path does not give you on
  local-fast-v2, with the reason (see scope note below).
• Document index and the repository-layout note now route "deploy" and
  "develop" to the right file.

docs/RUN_LOCAL.md

• Retitled as development-only, with a pointer back to the container path.
• Added the same platform-equivalence table, plus a 不装 Homebrew：依赖容器 +
  进程应用 route for apt-based hosts (dev_up.sh only discovers Homebrew kegs).
• Notes the architecture variants for MinIO binaries and the WSL2 reachability
  conditions for Ollama.

CHANGELOG.md — [Unreleased] Added + Changed entries.

Refs #109

Scope note on the model boundary

An earlier local draft claimed "Worker 模型默认值全为空". That is wrong and is not
in this PR: worker/mem_worker/config.py:116-123 does ship non-empty
MEM_DEFAULT_* values. The accurate statement is per-profile and per-stage —
server/internal/aiprofile/catalog.go:347-371 enables only text embedding
(ollama:qwen3-embedding:0.6b, 768 dims) with a text/PDF MIME allow-list and
leaves VisualEmbedding, LLM, VLM, ASR and Rerank as empty stages,
while deploy/compose/compose.yaml keeps backend internal and points the
worker's OLLAMA_BASE_URL at its own 127.0.0.1:11434. The docs now say that.

Validation ledger

#	Check	Expected	Actual
1	Compose exposes only the edge	Only web publishes a host port; backend is internal	awk scan over deploy/compose/compose.yaml → web: HAS ports is the only hit; networks.backend.internal: true; MinIO pin RELEASE.2025-04-22T22-12-26Z, images pgvector/pgvector:0.8.1-pg16, redis:7.4.2-alpine
2	generate-env.sh claims	Refuses to overwrite, writes 0600, needs openssl	deploy/compose/generate-env.sh:4-11 ([ -e "$output" ] → exit 1, openssl is required), :14 umask 077, :39 reports mode 0600
3	Registration default	first_user	compose.yaml:21, .env.example:6
4	Hardware baseline	Matches docs/DEPLOYMENT.md	DEPLOYMENT.md:105 — 4 vCPU / 8 GiB / 80 GiB model-free
5	dev_up.sh cross-platform claims	Homebrew prefix resolution, setsid on Linux, vector.so/vector.dylib, @17/@18/@16 autodetect	scripts/dev_up.sh:29-36, :96-114, :127-134; "kept in sync with server/.env.example + worker/.env.example" at :38
6	Dependency-container route ports	Postgres :5432, Redis host :6479, MinIO host :9100, memd/worker commented out	root docker-compose.yml:8-101
7	server/.env.example Redis default	Empty → in-process fallback	server/.env.example:17 MEM_REDIS_URL=
8	Worker dotenv claim	Worker reads worker/.env	worker/mem_worker/config.py:41 env_file=".env"
9	Fail-closed profile probe	Dimension probe failure does not persist a selection	server/internal/aiprofile/service.go:389-395 (ErrEmbeddingProbeFailed / ErrEmbeddingDimensionMismatch), surfaced as 422 ai_profile_embedding_dimension_mismatch at server/internal/api/handlers_ai_profile.go:92
10	Anchors after heading renames	No inbound link breaks	## 开始使用 exists and is the only #开始使用 target (docs/RUN_LOCAL.md:4); repo-wide grep for 快速开始 finds only web/README.md's own heading
11	Branch base	Created from latest main	Rebased onto e6f082b (#118); upstream touched only CHANGELOG.md in these paths since the old base, no conflict

Not run, and deliberately not claimed:

• AC-002 (clean-environment runbook evidence). I did not bring the stack up
  on a fresh host for this PR. The closed-loop statement in the README is
  attributed to the ops dogfood record in docs(onboarding): make deploy/compose the primary onboarding path #109 rather than presented as
  first-party evidence from this change.
• No Go/Python/JavaScript source is touched, so make lint, make test-all and
  the protobuf regeneration checks were not run locally; CI covers them.

Rollback

Revert 3668d41. Documentation-only: no runtime, schema, compose topology or
release-artifact impact, so no data migration or cache invalidation is implied.

Governance gate — this PR should not merge yet

Per AGENTS.md rule 2, implementation waits for acceptance criteria and the
status:ready label. #109 has AC-001..003 but is still R1 status: needs-design
with technicalOwner: unassigned, so this is opened as a draft for early
feedback (org CONTRIBUTING.md: drafts are welcome, not merge-eligible).

• @PeterGuy326 as productOwner: promote docs(onboarding): make deploy/compose the primary onboarding path #109 to status:ready (R2), or amend the
  requirements if the container-first framing is not what you want.
• AC-002 still needs a clean-host runbook capture before this can be marked done.
• The open decision in docs(onboarding): make deploy/compose the primary onboarding path #109 about whether first-run container-path detection
  belongs in a shared mem doctor surface is being tracked in feat(cli): add mem doctor and first-run guidance that names the documented deploy/compose path #112; feat(cli): add mem doctor and first-run guidance that names the documented deploy/compose path #112 is also
  still needs-design, so the two should be adjudicated together.

[PeterGuy326]

Draft audit at 3668d4169dfd6c048b5c715eeddef36cccd785b9

The exact-head 11/11 checks and focused local validation are green, but this draft is not ready for review or merge.

P1 content gaps

1. The recommended Compose topology exposes only 127.0.0.1:8080, while the primary CLI login and MCP quick-start examples still target the fresh-config default localhost:8787. A new user following the main path reaches an unpublished port. In Compose context, make mem --server http://127.0.0.1:8080 auth login the primary command and use 8080 in MCP examples; label 8787 as RUN_LOCAL/bare-metal only.
2. The Linux/WSL mixed runbook puts three foreground processes (make server, make worker, npm run dev) in one sequential shell block, so the first command prevents the other two from starting. Start dependencies with docker compose up -d --wait, then document separate Terminal A/B/C commands and cwd/env requirements.
3. The proposed acceptance text and CHANGELOG claim version-pinned equivalence, but the actual path still uses minio/minio:latest, minio/mc:latest, major-only tags, and moving unchecksummed MinIO downloads. This needs a product decision: either deliver real tags/digests/checksums, or narrow the requirement to clearly labeled mutable development aliases and remove the pin claim.

Hard gates

• docs(onboarding): make deploy/compose the primary onboarding path #109 remains R1 / needs-design / unassigned. The proposed R2 comment is not an owner decision and the canonical record/labels were not updated.
• AC-002 clean-host evidence is absent. Provide a safe evidence locator with OS/arch, Docker/Compose versions, exact SHA, commands/exits, health, first-user success, second-user rejection, and folder/upload/download results, then obtain independent review.
• The branch is two commits behind strict main; update only after scope is decided and preserve both CHANGELOG entries.
• Keep this as Draft until the above is resolved; then rerun exact-head checks and request independent CODEOWNER review.

Additional cleanup: retitle RUN_LOCAL.md to cover both bare-metal and dependency-container development; do not claim lockfiles pin interpreters; avoid overwriting an existing worker/.env; and keep README concise by linking deployment detail rather than duplicating it.

[PeterGuy326]

Review status: HOLD, not an approval. The draft is conflicted with current main; more importantly, canonical Issue #109 remains R1 needs-design and the stated AC-002 clean-environment onboarding closure is not yet evidenced. Existing green checks do not substitute for those prerequisites.

Please preserve Draft status, establish the ready requirement/decision and complete the clean-environment acceptance evidence first, then synchronize to current main and rerun the exact-head checks before requesting a final review.

[PeterGuy326]

ByteFolk cutover blocker (exact head 3668d4169dfd6c048b5c715eeddef36cccd785b9):

• README.md still contains old GitHub clone, badge, Issue, and contribution links under github.com/fullstack-ai-infra; migrate them to github.com/bytefolk.

Please update the fork branch and rerun CI before merge.

[PeterGuy326]

Closing this dirty draft under bytefolk/.github#24 AC-004. The requirement remains in #109 R2, and #148 is the newer implementation candidate. This closure is not acceptance of #148: the replacement still needs a clean final tree, the required clean-host Compose evidence, fresh CI, and independent review before merge. No requirement or historical evidence is deleted.