feat: P1 profile/portrait API and freeze local-dev environment

Add host-first environment contracts (Local vs CI vs Prod), deps-only
compose, and the Profile → Portrait → deep-access mock payment slice
with device identity and auto-migrate on API startup.

Co-authored-by: Cursor <cursoragent@cursor.com>

.ai/commands.md

@@ -1,67 +1,79 @@
 # Commands — Do Not Guess
 
-Run from repo root unless noted.
+Run from **repo root** unless noted.  
+Policy: [environment.md](environment.md) · [development.md](development.md)
 
-## Go API (`apps/api`)
+本仓库用 **npm workspaces**（`npm run …`）；等价于文档中的 pnpm 习惯用法。
+
+---
+
+## Local Development — First time
+
+1. Install host toolchains: Go 1.22+ · Node 20+ · Docker Desktop（仅依赖服务）  
+2. `npm install`  
+3. `npm run deps:up`（或 `docker compose -f docker-compose.dev.yml up -d`）  
+4. Start API once so migrations apply: `cd apps/api && go run ./cmd/server`  
+5. Verify: `curl -s http://127.0.0.1:8080/api/v1/healthz`  
+6. Start H5: `npm run dev:h5` → http://127.0.0.1:5173  
+
+Optional CN Go proxy: `export GOPROXY=https://goproxy.cn,direct`  
+Optional API hot reload: install `air`, then `cd apps/api && air`（见 `.air.toml`）
+
+---
+
+## Local Development — Daily
 
 ```bash
-export GOPROXY=https://goproxy.cn,direct   # if download timeout
+# Terminal 1 — infrastructure only
+npm run deps:up
 
+# Terminal 2 — backend (host)
+cd apps/api
+air
+# 或: go run ./cmd/server
+
+# Terminal 3 — frontend (host)
+npm run dev:h5
+```
+
+Stop deps: `npm run deps:down`
+
+---
+
+## Go API
+
+```bash
 cd apps/api
 go mod tidy
-go build ./...
 go test ./...
+go build ./...
 go run ./cmd/server
 ```
 
-Health:
+Env defaults / template: `deploy/.env.example`  
+Migrate: applied on API startup (`apps/api/migrations/*.up.sql`)
 
 ```bash
 curl -s http://127.0.0.1:8080/api/v1/healthz
 curl -s http://127.0.0.1:8080/api/v1/ping
 ```
 
+**Do not** `docker build` the API for everyday coding.
+
+---
+
 ## User H5
 
 ```bash
-npm install
 npm run dev:h5
 npm run build:h5
 ```
 
-## Docker / DB
+**Do not** dockerize Vite for everyday coding.
 
-```bash
-docker compose -f deploy/docker-compose.yml up -d
-docker compose -f deploy/docker-compose.yml down
-```
+---
 
-## Lint (when configured)
+## CI / production
 
-```bash
-# Go — after golangci-lint is added:
-# cd apps/api && golangci-lint run
-
-# H5 — after eslint is added:
-# npm run lint -w @yuxingu/user-h5
-```
-
-## Migrations (when make targets exist)
-
-```bash
-# Preferred once Makefile lands:
-# make migrate
-# make migrate-down
-
-# Until then: document the goose/migrate command used in the PR.
-```
-
-## Dev all (local)
-
-```bash
-# terminal 1
-cd apps/api && go run ./cmd/server
-
-# terminal 2
-npm run dev:h5
-```
+见 [deployment.md](deployment.md) · [docker.md](docker.md)。  
+仅在发布/CI 任务使用镜像与 `deploy/docker-compose.prod.yml`。