rush-ai 0.12.0 → 0.13.0

package/dist/{install-AGHG4XKQ.js → install-RTV2VWCC.js}

@@ -8,7 +8,7 @@ import {
   ApiError,
   createClient,
   output
-} from "./chunk-3X5X3ZTX.js";
+} from "./chunk-YKZIRW26.js";
 
 // src/commands/mcp/config-writers.ts
 import { randomUUID } from "crypto";
@@ -570,4 +570,4 @@ export {
   runMcpInstall,
   runMcpUninstall
 };
-//# sourceMappingURL=install-AGHG4XKQ.js.map
+//# sourceMappingURL=install-RTV2VWCC.js.map

package/dist/{server-GQMH2YN4.js → server-Y2CXHDCK.js}

@@ -5,7 +5,7 @@ import {
 import {
   createClient,
   getAuthToken
-} from "./chunk-3X5X3ZTX.js";
+} from "./chunk-YKZIRW26.js";
 
 // src/commands/mcp/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -656,4 +656,4 @@ async function startMcpServer() {
 export {
   startMcpServer
 };
-//# sourceMappingURL=server-GQMH2YN4.js.map
+//# sourceMappingURL=server-Y2CXHDCK.js.map

package/dist/skills/README.md

@@ -16,7 +16,7 @@ Pick the guide that matches the situation:
   → Read [`push-local-project.md`](./push-local-project.md). Typical trigger: "同步一下 pod", "我本地改了代码推到 rush", "put the latest commits on the preview URL". `task push` does git push + pod sync/pull + Vite HMR — it does **not** create projects. (Journey J-2.)
 
 - **The user has a local project that needs its own database and/or OSS storage on Rush — not just a preview.**
-  → ⚠️ **Currently not recommended.** The `task link` path is blocked by #1147 (GitLab deploy-token scope rejected). For now, route these users to [`hand-off.md`](./hand-off.md) — ask them to describe the site (or attach files) and let `task create -a web-builder` rebuild it from scratch. Do not invoke `task link`; it will 502 at the finalize step. (Journey J-3 is paused.)
+  → Read [`project-setup.md`](./project-setup.md). Typical trigger: "把这个项目接入 Rush，要带数据库", "this repo uses Supabase / file uploads, set it up on Rush". `task link --db --oss` provisions the pod + DB + storage endpoint and emits an agent handoff. (Journey J-3.)
 
 - **The user has an existing web-builder project and wants to publish it to production / a custom domain.**
   → Read [`deploy-to-prod.md`](./deploy-to-prod.md). Typical trigger: "把这个站上线", "换成 my-app.rush.zhenguanyu.com", "deploy to prod". Works only for web-builder projects with a non-null template. (Journey J-4.)
@@ -29,8 +29,6 @@ Pick the guide that matches the situation:
 
 `hand-off.md` vs `push-local-project.md`: hand-off is **"let Rush create a new project from my prompt"**; push-local-project is **"sync my already-existing Rush project's local commits back to the pod preview"**. Heuristic: check `git -C . config --get remote.origin.url`. If origin is `gitlab-ee.zhenguanyu.com/rush/dev/<id>` (or `.rush/env.md` exists with a `PROJECT_ID`), the user is inside a Rush project — lean push. If there's no Rush identity on disk, lean hand-off.
 
-Note on the retired `project-setup` skill: previous versions shipped a `project-setup.md` that documented `task link --db --oss`. It has been removed from this package because the `task link` path is currently blocked (#1147 — GitLab deploy-token scope rejected). Until it's unblocked, route any "set this project up with its own DB / OSS on Rush" ask to [`hand-off.md`](./hand-off.md) and let `task create -a web-builder` rebuild the project from scratch. `task push` (this skill family) only syncs existing Rush projects; it does not provision.
-
 Still unsure? Run `npx rush-ai agent list` first — seeing the available agents usually makes the decision obvious.
 
 ## Cheat sheet

package/dist/skills/deploy-to-prod.md

@@ -15,12 +15,11 @@ Triggers (not exhaustive — use judgement):
 Do NOT use this skill for:
 
 - **"Build me a new site from a prompt."** → No project exists yet. Use [`hand-off.md`](./hand-off.md) first; come back here after the project is ready.
-- **"Sync my local Rush project back to the pod (preview URL)."** → That's the J-2 sync path now; use [`push-local-project.md`](./push-local-project.md) (`task push`). `task push` does **not** create new projects — it syncs an existing one — so it does not produce fresh `template = null` projects anymore (see the banner below for how this differs from the old flow).
+- **"Sync my local Rush project back to the pod (preview URL)."** → That's the J-2 sync path; use [`push-local-project.md`](./push-local-project.md) (`task push`). `task push` does **not** create new projects — it only syncs commits onto an existing one.
+- **"Wire my non-Rush local repo into Rush with DB / OSS, then publish to a custom domain."** → Two skills, in order: first [`project-setup.md`](./project-setup.md) (`task link --db --oss`) to provision; **but note** `task link` projects have `template = null` and currently CANNOT flow through `task deploy` (epic #1096 Phase 2 — not shipped). For a custom-domain publish today, the project must originate from `task create -a web-builder`, not `task link`.
 - **Next.js production database provisioning** — `task deploy` only *checks* the prod DB exists (for nextjs templates); creating it is done in the Web UI.
 - **Rolling back a deploy.** There is no `rush-ai task rollback`; redeploy an earlier version via `--version <hash>` (see Playbook step 2).
 
-> ⚠️ **"将本地非 Rush 项目接入 Rush 再发 prod"暂不可用**: `task link` 的 GitLab deploy-token 步骤当前被 #1147 block。如果用户的项目不是从 Rush GitLab clone 出来的（且他们需要 DB/OSS），暂时请引导他们走 [`hand-off.md`](./hand-off.md) 重新起一个 `task create -a web-builder` 项目，而不是 `task link` 再 `task deploy`——后者目前会在 finalize 阶段 502。
-
 ## Decision
 
 Users often conflate three different operations. Use this table before any command runs:
@@ -30,7 +29,7 @@ Users often conflate three different operations. Use this table before any comma
 | User has a web-builder project (has `template`, `agent = web-builder`), wants a production / custom-domain URL | **this skill** (`task deploy <id>`) |
 | User is inside a Rush project working tree and wants the pod preview URL to catch up with local commits | [`push-local-project.md`](./push-local-project.md) (`task push` — sync only, no deploy) |
 | User wants to generate a brand-new site from a prompt | [`hand-off.md`](./hand-off.md) (`task create -a web-builder`) |
-| User wants to "deploy" a `task link` project (template = null) to a custom domain | **Not supported today.** `task link` itself is currently blocked by #1147 — see the banner above. |
+| User wants to "deploy" a `task link` project (template = null) to a custom domain | **Not supported today.** `task link` produces `template = null`; the conversion-to-template flow is epic #1096 Phase 2, not shipped. Use `task create -a web-builder` if a custom-domain publish is the end goal. |
 
 Fast sanity check before invoking any command in this skill:
 
@@ -139,7 +138,7 @@ Common failure paths to surface verbatim to the user:
 
 - `No versions yet. Send a message first.` → step 3 was skipped or the project has no builds.
 - `Build artifacts missing for commit <short>. Send a new message to rebuild.` → non-nextjs only. The OSS-backed build for that commit was never produced (or was cleaned up). Tell the user to `task send <id>` to trigger a rebuild.
-- `Production database not created. Open Web UI to create.` → nextjs-only preflight. The CLI cannot create the prod DB; the user must click through the Web UI.
+- `Required database is not configured. Open the Web UI to provision it before deploying.` → nextjs-only preflight. The CLI cannot create the required database; the user must click through the Web UI.
 - `409 Conflict` on the publish call → TOCTOU: someone else grabbed the prefix between step 4 and step 5. Loop back to step 4 with a new prefix.
 - SSE "Deployment stream disconnected unexpectedly" → nextjs publish-pod stream dropped mid-flight. Do NOT retry automatically; tell the user, let them retry manually.
 
@@ -161,13 +160,13 @@ To deploy a different branch/version to the **same** domain: `--version <otherHa
 
 ## Limitations
 
-- **Only web-builder projects with a non-null `template`.** `task deploy` refuses non-web-builder agents and `template = null` projects. Historically `task link` produced `template = null` projects; note that `task link` itself is currently blocked (#1147), so the more likely failing case today is a pre-existing `task link`-produced project in the user's history. (A "convert a non-template project into a template-backed project" flow is planned but **not shipped** — don't promise it.)
+- **Only web-builder projects with a non-null `template`.** `task deploy` refuses non-web-builder agents and `template = null` projects. `task link`-produced projects have `template = null` and CANNOT flow through `task deploy` — for custom-domain publishes the user must start from `task create -a web-builder`. (A "convert a non-template project into a template-backed project" flow is planned as epic #1096 Phase 2 but **not shipped** — don't promise it.)
 - **Next.js (`template = nextjs-fullstack`) forces `--env production`.** The publish-pod endpoint is server-hardcoded to `online`. `--env test` is rejected with a clear error. Non-nextjs templates support both `test` and `production`.
-- **Next.js also requires a provisioned production database.** If `hasProduction === false` the CLI aborts with `Production database not created. Open Web UI to create.` — this is **not** something the CLI can fix; the user must create it via the Web UI.
+- **Next.js also requires a provisioned database for the selected production source.** If `hasSelectedDatabase === false` the CLI aborts with `Required database is not configured. Open the Web UI to provision it before deploying.` — this is **not** something the CLI can fix; the user must create it via the Web UI.
 - **Domain prefix is global across Rush.** If someone else registered `my-app`, you can't have it. Use `task domain check` before deploy.
 - **No automatic rollback.** To "roll back," deploy an earlier `--version <hash>`. There is no `task deploy --rollback`.
 - **No retry on SSE stream drop (nextjs).** Publish-pod is a side-effecting POST; if the stream drops before a terminal event the CLI fails with `Deployment stream disconnected unexpectedly`. **Do not** re-invoke `task deploy` reflexively — re-posting can start a duplicate publish. Tell the user to check the Web UI / `task versions <id>` to see whether the deploy actually landed before retrying.
-- **`--yes` skips the confirmation prompt but not gating.** All preflight checks (web-builder gate, version list, build-check / has-production, domain check) still run. It only bypasses the interactive "proceed? y/n" prompt.
+- **`--yes` skips the confirmation prompt but not gating.** All preflight checks (web-builder gate, version list, build-check / database availability, domain check) still run. It only bypasses the interactive "proceed? y/n" prompt.
 
 ## Anti-patterns
 

package/dist/skills/hand-off.md

@@ -18,8 +18,7 @@ Do NOT use this skill for:
 - The user already has a **Rush** project checked out locally and wants to sync local commits back to the pod — use [`push-local-project.md`](./push-local-project.md) (`task push`) instead of creating a new task from scratch.
 - The user already has a web-builder project and wants to publish it to prod / a custom domain — use [`deploy-to-prod.md`](./deploy-to-prod.md) (`task deploy`), not a new hand-off.
 - The user wants text / analysis / structured output (no preview URL) — use [`general-task.md`](./general-task.md) with `-a rush`.
-
-> ⚠️ **"接入非 Rush 本地项目"暂不可用**: `task link`（原 `task init`）的 GitLab deploy-token 步骤当前被 #1147 block（目标实例拒绝 `write_repository` scope）。如果用户有一个本地项目（非 rush 源）想接入 Rush——包括需要 DB / OSS 的 J-3 场景——暂时请走 `task create -a web-builder`（本 skill）从 prompt / 文件重建，不要引导用户去 `task link`。
+- The user has a local project (non-Rush) that needs its own database and/or OSS storage on Rush — use [`project-setup.md`](./project-setup.md) (`task link --db --oss`).
 
 ## Decision: which agent?
 

package/dist/skills/project-setup.md

@@ -0,0 +1,203 @@
+# Skill: Wire a local project into Rush with its own DB and object storage
+
+Use this skill when the user has a **local codebase they've been developing** (typically a Next.js app or a Vite SPA with Supabase / file uploads wired up) and wants it running on Rush **with its own Supabase database and/or Rush-proxied object storage** — not just a throwaway preview. This is the J-3 full-setup path: `rush-ai task link` provisions the pod + DB + storage endpoint, writes credentials to `.rush/env.md`, and emits a machine-consumable checklist at `.rush/agent-handoff.md` telling you (the IDE agent) exactly which local files to edit to finish the wiring.
+
+## When this skill applies
+
+Triggers (not exhaustive — use judgement):
+
+- "帮我把这个项目接入 Rush，要带自己的数据库。"
+- "这个仓库要部署到 Rush，里面用到了 Supabase / 文件上传。"
+- "Set up this repo on Rush with a real database, not just a preview."
+- The user points at a working directory with `package.json` + a `dev` script AND any of: `supabase/migrations/`, an `.env.local` that references `DATABASE_URL` / `SUPABASE_URL` / `POSTGRES_URL`, or a `public/` directory heavy with user-upload-style assets.
+
+Do NOT use this skill for:
+
+- **"Just give me a shareable preview URL — no database needed."** → Use [`push-local-project.md`](./push-local-project.md) (`task push`). That path skips DB + OSS and gets the user a `{projectId}-preview.rush.zhenguanyu.com` URL in the fewest steps.
+- **"Build me a new site from scratch / from this prompt."** → There is no local project yet. Use [`hand-off.md`](./hand-off.md) with `-a web-builder`.
+- **"Publish an existing web-builder project to a custom domain."** → That's the J-4 path. Use [`deploy-to-prod.md`](./deploy-to-prod.md). Note: `task link` projects have `template = null`, so they **cannot** flow through `task deploy` today (see Limitations).
+- **First-time install / login (401, doctor)** → Use [`onboarding.md`](./onboarding.md); do not fall through to `task link` on a 401.
+- **Sub-agent or text-only work** → [`agent-shelf.md`](./agent-shelf.md) / [`general-task.md`](./general-task.md).
+
+## Decision
+
+Pick the **smallest** path that covers the user's actual need. DB + OSS provisioning is heavier than a preview push — don't invoke it reflexively.
+
+| Situation | Skill |
+|---|---|
+| Local project needs its own DB and/or OSS uploads to work | **this skill** (`task link --db --oss`) |
+| Local project just needs a shareable URL, no persistent storage | [`push-local-project.md`](./push-local-project.md) (`task push`) |
+| No local project yet; generate from a prompt | [`hand-off.md`](./hand-off.md) |
+| Existing web-builder project, want custom domain / production deploy | [`deploy-to-prod.md`](./deploy-to-prod.md) |
+
+Fast sanity check before any command runs:
+
+```bash
+# Is there a local project here at all?
+test -f package.json && grep -q '"dev"' package.json && echo "yes" || echo "no"
+
+# Does it want a database?
+grep -lE '\b(DATABASE_URL|SUPABASE_URL|POSTGRES_URL|USER_POSTGRESQL_URL)\s*=' .env .env.local .env.development 2>/dev/null || echo "no db signal"
+test -d supabase/migrations && echo "has migrations" || echo "no migrations"
+```
+
+If there is no local project → route to `hand-off.md`. If there's a project but no DB / upload signal → default to `push-local-project.md`; only escalate to this skill when the user explicitly asks for DB / OSS.
+
+## Playbook
+
+### 1. Detect what the project actually needs
+
+Run a quick survey of the working directory before touching the network. Surface what you found to the user so the `--db / --oss` decision is explicit, not a guess:
+
+```bash
+# DB signals
+ls -1 .env .env.local .env.development 2>/dev/null
+grep -lE '\b(DATABASE_URL|SUPABASE_URL|POSTGRES_URL|USER_POSTGRESQL_URL)\s*=' \
+    .env .env.local .env.development 2>/dev/null
+test -d supabase/migrations && ls supabase/migrations | head -3
+
+# OSS / upload signals
+du -sk public 2>/dev/null
+# heavy public/ OR an existing upload helper (oss-client, signed URL, etc.) → OSS worth provisioning
+```
+
+Report back to the user:
+
+> 检测到 `.env.local` 里有 `DATABASE_URL`，`supabase/migrations/` 下 3 个迁移脚本；public/ 2.1 MB（12 个 >50 KB 的资源）。建议 `--db --oss`。
+
+Let the user confirm or override before running step 3. `task link` is idempotent but it does provision real resources — don't guess.
+
+### 2. Verify auth + local-readiness preflight
+
+```bash
+npx rush-ai auth status --json
+npx rush-ai check --json
+```
+
+`auth status`:
+- **Authenticated** → proceed to step 3.
+- **Not authenticated** → STOP. Print this to the user and wait:
+
+  > Rush 还没登录。请在终端里跑 `npx rush-ai auth login`（会打开浏览器完成 CAS 登录），登录完告诉我一声。
+
+  Do NOT run `auth login` yourself (it opens a browser). Do NOT fall through to `task link` — it will 401.
+
+`check`:
+- Exit 0 → the project is ready for the pod (has `dev` script, reads `PORT`, lock file present, etc.).
+- Non-zero → fix the `checks[].fix` items first. `task link` itself will re-run `check` and abort on errors; running it now gives the user an actionable report up front.
+
+### 3. Provision with `task link`
+
+Invocation (include / omit `--db` / `--oss` to match the decision from step 1):
+
+```bash
+npx rush-ai task link --db --oss --name <slug>
+```
+
+Append the global `--json` flag when you need machine-readable output:
+
+```bash
+npx rush-ai task link --db --oss --name <slug> --json
+```
+
+Subcommand flags (the complete set — `task link` does not accept anything else):
+
+- `--db`: create a Supabase database for this project. Omit if the user's project doesn't need one.
+- `--oss`: record the Rush-proxied storage endpoint (`STORAGE_API_BASE`) in `.rush/env.md`. Authentication reuses the existing `RUSH_PLATFORM_TOKEN` — no per-project token is minted. Omit if the project doesn't upload files.
+- `-n, --name <slug>`: human-friendly project name. Defaults to the current directory's basename.
+- `-p, --path <dir>`: project directory. Defaults to `.` (cwd).
+- `-y, --yes`: skip interactive prompts; accept detected defaults.
+
+Global flags that apply (inherited from `rush-ai`, documented in `README.md` §Cheat sheet): `--json` for machine-readable output, `--no-color` for plain text.
+
+What `task link` does internally (so you can explain failures without guessing):
+
+1. **Detect** — same scan you did in step 1, plus reading any existing `.rush/env.md` (resume path).
+2. **Create pod** via `/api/tasks/deploy` → writes `PROJECT_ID`, `PREVIEW_URL`, masked `GIT_REMOTE`, `STATE=pod-only`.
+3. **Create DB** (if `--db`) via `/api/projects/:id/database/create` → writes `DATABASE_URL`, `SUPABASE_URL`, `STATE=pod-db`.
+4. **Record storage endpoint** (if `--oss`) → writes `STORAGE_API_BASE=https://rush.zhenguanyu.com/api/tasks/<projectId>/storage`, `STATE=pod-db-oss`. No server round-trip: the storage API is unconditionally available for any task and authentication reuses the existing `RUSH_PLATFORM_TOKEN`.
+5. **Finalize** — `STATE=complete`, write `.rush/agent-handoff.md`, ensure `.rush/` is in `.gitignore`.
+
+On success, `--json` prints:
+
+```json
+{
+  "projectId": "…",
+  "previewUrl": "https://…-preview.rush.zhenguanyu.com",
+  "state": "complete",
+  "db":      { "databaseUrl": "postgresql://…", "supabaseUrl": "https://…" },
+  "storage": { "storageApiBase": "https://rush.zhenguanyu.com/api/tasks/…/storage" },
+  "files":   { "env": "…/.rush/env.md", "handoff": "…/.rush/agent-handoff.md" }
+}
+```
+
+Failure modes to surface verbatim:
+
+- `Database create failed: <reason>` → DB step failed. The pod is already up (`STATE=pod-only` persisted). Re-run `task link --db` to resume from that checkpoint after the user fixes the cause.
+- Any error → `.rush/env.md` is preserved with the last good `STATE`. Re-running `task link` with the same flags picks up from there; it will not re-create pods / DBs that already exist.
+
+### 4. Consume the handoff (apply local edits)
+
+Open `.rush/agent-handoff.md` — `task link` wrote it fresh on success. It's a per-project checklist of the **local code changes** you need to make. You (the IDE agent), not the user, are expected to do these:
+
+- **Database** (if `--db` was used):
+  - Swap `DATABASE_URL` / `SUPABASE_URL` in `.env.local` to the values recorded in `.rush/env.md`.
+  - Run the migrations in `supabase/migrations/*.sql` against the new database (or `supabase db push` if the CLI is wired up).
+  - (Optional) Migrate local data.
+- **File uploads** (if `--oss` was used) — **double-hop proxy pattern**:
+  - Browser → user-app server route → rush-app storage API. The browser never holds a bearer credential.
+  - Add a server-side upload route in the user's app that forwards multipart form data to `${STORAGE_API_BASE}/upload` with `Authorization: Bearer ${RUSH_PLATFORM_TOKEN}`:
+
+    ```ts
+    // app/api/upload/route.ts (Next.js example)
+    export async function POST(req: Request) {
+      const formData = await req.formData();
+      const rushRes = await fetch(`${process.env.STORAGE_API_BASE}/upload`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${process.env.RUSH_PLATFORM_TOKEN}` },
+        body: formData,
+      });
+      return Response.json(await rushRes.json());
+    }
+    ```
+
+  - In the browser, hit the user-app upload route (not Rush directly) with `FormData`. Display uploaded files with `<img src={url} />` — the returned URL is already a Rush-hosted proxy endpoint that serves the bytes.
+  - Delete / list endpoints follow the same proxy pattern: `DELETE ${STORAGE_API_BASE}/object/<key>` and `GET ${STORAGE_API_BASE}/list` (also server-side with the Platform Token).
+- **Verify**: open `PREVIEW_URL` and exercise the DB + upload paths.
+
+Read the actual handoff file for each project — it specializes the checklist to what `detectNeeds` found (e.g. it adds the migration line only if `supabase/migrations/` exists).
+
+### 5. Push the edited code and verify end-to-end
+
+```bash
+npx rush-ai task push --json
+```
+
+`task push` identifies the existing Rush project from `.git/remote.origin.url` (set by the initial push that `task link` performed) with `.rush/env.md` `PROJECT_ID` as fallback, pushes with the user's own git credentials, and triggers `POST /api/repository/sync/pull` so the pod's dev server picks up the change. It does **not** create projects (#1149): if neither source resolves to a Rush project, `task push` exits with `NO_RUSH_PROJECT` and points the user at `task create` / `task link`.
+
+Once `task push` returns `status: "ready"`:
+
+- Present the preview URL (same as the one `task link` emitted).
+- Tell the user to hit it and confirm DB + upload end-to-end.
+- If something's off, iterate via `task send <projectId> -p "…"` on the pod, or edit locally and `task push` again.
+
+## Limitations
+
+- **`.rush/env.md` must never be committed.** `task link` auto-appends `.rush/` to `.gitignore` and writes a `# DO NOT commit — contains credentials` banner at the top of the file on every save. If the user accidentally committed it, tell them to rotate credentials (new DB password / new Platform Token) — you cannot "undo" an exposed secret.
+- **`task link` is compensating, not atomic.** Each successful remote call writes a `STATE` checkpoint (`pod-only` → `pod-db` → `pod-db-oss` → `complete`). A failure mid-way leaves partial state on disk. **Do not** delete `.rush/env.md` to "start over" — re-run `task link` with the same flags and it will resume from the last good checkpoint without re-provisioning what already exists. Deleting the file means the next `task link` creates a fresh pod + leaks the old one.
+- **Platform Token is server-side only.** The `RUSH_PLATFORM_TOKEN` used to authenticate storage uploads lives on the user-app server (via the existing Rush CLI login flow). **Never** fetch the storage API directly from the browser carrying a bearer token — always go through a user-app server route that holds the token in `process.env`. The `task link` handoff enforces this pattern.
+- **Uploaded objects are publicly readable via their URL.** `GET /api/tasks/<id>/storage/object/<key>` is anonymous by design so the URL can be used in `<img src>` / `<a href>`. Do not store secrets, private user data, PII, or anything else that shouldn't be public through this path. If the project needs private storage, this skill is not the right fit today.
+- **Single-file upload size is capped at 30 MB; total per-task storage at 5 GB.** The Rush storage proxy responds `413 PAYLOAD_TOO_LARGE` / `507 INSUFFICIENT_STORAGE` when exceeded. Streaming uploads for larger files are on the Phase 2 roadmap but not shipped.
+- **Projects created via `task link` have `template = null`.** They CANNOT flow through `rush-ai task deploy` / custom-domain publish. The `{projectId}-preview.rush.zhenguanyu.com` URL is the only address. A "convert to template-backed project" flow is planned (epic #1096 Phase 2) but **not shipped**.
+- **`task link` never edits user code.** All local mutations happen via your application of `.rush/agent-handoff.md`. The command only writes under `.rush/` (env file + handoff) and touches `.gitignore` to append the ignore rule.
+
+## Anti-patterns
+
+- ❌ Running `task link --db --oss` without showing the user the detection summary first. They may not actually want a DB; you just provisioned real resources.
+- ❌ Committing `.rush/env.md`. Don't. If it happens, treat the credentials as compromised.
+- ❌ Deleting `.rush/env.md` to "retry" a failed `task link`. That orphans whatever was already created. Re-run `task link` with the same flags to resume.
+- ❌ Fetching the storage API directly from the browser with a bearer token. `RUSH_PLATFORM_TOKEN` is server-side only — always proxy through a user-app server route. Exposing it in a client bundle or public env var is a credential leak.
+- ❌ Hand-writing signed upload URLs or trying to use OSS SDKs directly — the new design is Rush-proxied. The only storage surface is `https://rush.zhenguanyu.com/api/tasks/<id>/storage/*`.
+- ❌ Calling `task deploy <id>` on a `task link`-produced project. `template = null` — it will reject at the gate. Use `task push` for iterative updates; route users to `hand-off.md` if they want a custom domain.
+- ❌ Inventing flags. `task link`'s subcommand flags are exactly `--db`, `--oss`, `-n/--name <slug>`, `-p/--path <dir>`, `-y/--yes` — plus the global `--json` / `--no-color`. No `--rotate`, no `--dry-run`, no `--force`, no `--env`.
+- ❌ Running `task push` straight away when the user asked for DB / storage. `task push` only syncs an existing Rush project (it exits with `NO_RUSH_PROJECT` if there isn't one) and never provisions a DB, never records the storage endpoint, never produces a handoff. For DB / OSS you must run `task link` first.

package/dist/skills/push-local-project.md

@@ -16,23 +16,19 @@ Triggers (not exhaustive — use judgement):
 Do NOT use this skill for:
 
 - **"Build me a new site from a prompt" / "Start a fresh project."** → Use [`hand-off.md`](./hand-off.md) with `-a web-builder`. `task push` will refuse with `NO_RUSH_PROJECT` because there's no Rush project yet.
-- **"Wire my existing (non-Rush) local repo into Rush with its own DB / OSS."** → This path (`task link`) is **currently not recommended** — see the banner below. For now, tell the user to start fresh with `task create -a web-builder` and ask the web-builder agent to rebuild their project.
+- **"Wire my existing (non-Rush) local repo into Rush with its own DB / OSS."** → Use [`project-setup.md`](./project-setup.md) (`task link --db --oss`). `task push` does not provision DB / storage.
 - **"Publish this web-builder project to a custom domain / production."** → Use [`deploy-to-prod.md`](./deploy-to-prod.md). `task push` only syncs the preview pod; it does not publish.
 - **First-time install / auth / login issues (401, `rush-ai doctor`).** → Use [`onboarding.md`](./onboarding.md).
 - **Sub-agent or text-only work.** → [`agent-shelf.md`](./agent-shelf.md) / [`general-task.md`](./general-task.md).
 - **Small local edits the user wants applied in the current repo.** → Just do them; don't round-trip to Rush for every tweak.
 
-### Banner: `task link` (接入非 Rush 本地项目) 暂不可用
-
-> ⚠️ `task link` 的 GitLab deploy-token 流程当前因 `write_repository` scope 被 test 实例拒绝而 block（#1147）。如果用户的本地项目**不是**从 Rush GitLab clone 出来的（例如他们在 GitHub 上已有一个项目想"接入 Rush"），暂时不要引导他们走 `task link`——会在 finalize 阶段 502。临时方案：让用户走 `task create -a web-builder` 从 prompt / 文件描述重新起一个 rush project，再把本地代码手工迁过去（或等 #1147 修复）。
-
 ## Decision: push vs. the other skills
 
 | Situation | Skill |
 |---|---|
 | User is already inside a Rush-originated working tree and just wants the pod to catch up with local commits | **this skill** (`task push`) |
 | User wants Rush to generate a new site from a prompt | [`hand-off.md`](./hand-off.md) (`task create -a web-builder`) |
-| User wants to wire an existing non-Rush local repo into Rush (with DB / OSS) | **Not recommended today — see banner above.** Fall back to `task create -a web-builder`. |
+| User wants to wire an existing non-Rush local repo into Rush with its own DB / OSS | [`project-setup.md`](./project-setup.md) (`task link --db --oss`) |
 | User wants a custom domain / production publish of an existing web-builder project | [`deploy-to-prod.md`](./deploy-to-prod.md) |
 
 Fast sanity check before any command runs:
@@ -102,7 +98,7 @@ What `task push` does internally (so you can explain failures without guessing):
    - Parse `.git/config` `remote.origin.url`. If it matches `gitlab-ee.zhenguanyu.com/rush/dev/<id>`, extract `<id>`.
    - `GET /api/tasks/:id` to verify the project exists and is owned by the current user.
    - Fallback: read `.rush/env.md` `PROJECT_ID` (also verified against `GET /api/tasks/:id`).
-   - Both failed → exit `1` with `NO_RUSH_PROJECT`. The CLI prints a hint pointing at `task create` (or, historically, `task init` — which is now `task link` and, as noted in the banner, currently blocked).
+   - Both failed → exit `1` with `NO_RUSH_PROJECT`. The CLI prints a hint pointing at `task create` (for new projects) or `task link` (to wire an existing local repo into Rush with DB / OSS).
 3. **Auto-commit** — if the working tree has uncommitted changes, `git add . && git commit -m "deploy to rush"`. Users who want a different message should commit manually first.
 4. **`git push`** — routed based on how identity was resolved:
    - `projectSource='git-remote'` (the common path) → push to `origin` with the user's own git credentials. If the origin push fails AND env.md has a usable `GIT_REMOTE` (tokenised Rush URL from a previous CLI run), the CLI falls back to pushing that URL — useful in CI where the user's SSO credentials aren't available. If env.md has no usable `GIT_REMOTE`, the origin failure is surfaced as-is.
@@ -160,9 +156,9 @@ If `task push` exits non-zero:
 - **`task push` does not create projects.** If there's no Rush project for this working tree, the command exits with `NO_RUSH_PROJECT`. Use `hand-off.md` (`task create`) to start one.
 - **Each push syncs the same project.** The `previewUrl` does not change across pushes — the same project ID keeps its domain. This is a deliberate change from earlier versions where `task push` would fresh-create on every invocation; that old behaviour is gone (#1149).
 - **No pod restart.** The new flow uses `sync/pull` + Vite HMR; there is no `/api/tasks/:id/restart` call. Most of the time this is invisible (HMR works), but if the user changed `package.json` dependencies, the pod's `node_modules` won't install — they'd need to trigger an install explicitly (e.g. via `task send` asking web-builder to run it).
-- **No production deploy from a pushed project unless the project is a web-builder project with a non-null `template`.** If the project originated from `task create -a web-builder` it's deployable; if it came from the (currently-blocked) `task link` path it has `template = null` and can't flow through `task deploy`. Check `task status <id> --json | jq '{agent, template}'` before promising a custom domain.
+- **No production deploy from a pushed project unless the project is a web-builder project with a non-null `template`.** If the project originated from `task create -a web-builder` it's deployable; if it came from the `task link` path it has `template = null` and can't flow through `task deploy` (the conversion-to-template flow is epic #1096 Phase 2, not shipped). Check `task status <id> --json | jq '{agent, template}'` before promising a custom domain.
 - **No custom domain on the preview URL.** `{projectId}-preview.rush.zhenguanyu.com` is fixed. Custom domains are a `task deploy` feature — see `deploy-to-prod.md`.
-- **`task link` / "adopt an existing non-Rush repo" is currently blocked** (#1147). Do not route users there. See the banner at the top.
+- **`task link` is the path for "adopt an existing non-Rush repo" with its own DB / OSS.** It is **not** the same as `task push` — `task push` only syncs commits to an existing Rush project. If the user needs DB / storage provisioning, route to [`project-setup.md`](./project-setup.md).
 
 ## Example end-to-end
 
@@ -199,7 +195,7 @@ npx rush-ai task push --json
 
 - ❌ Running `task push` without first checking auth — you'll eat a 401 and confuse the user.
 - ❌ Running `task push` on an empty folder / a non-Rush repo expecting it to "create" a Rush project. It won't — it'll exit with `NO_RUSH_PROJECT`. Route to `hand-off.md`.
-- ❌ Suggesting `task link` / `task init` as a way to "adopt" a GitHub-origin project into Rush. That path is blocked on #1147 — don't steer the user into a 502.
+- ❌ Confusing `task link` with `task push`. `task link` provisions a fresh pod + DB / OSS for a non-Rush local repo (J-3, see [`project-setup.md`](./project-setup.md)); `task push` only syncs commits onto an existing Rush project's pod (J-2). Pick the right skill before suggesting either.
 - ❌ Skipping `rush-ai check` and pushing a project that doesn't read `PORT` — pod boots but serves nothing.
 - ❌ Retrying `task push` reflexively after a `SYNC_PULL_CONFLICT`. The pod has local changes; the user needs to rebase first or they'll keep bouncing off the conflict.
 - ❌ Telling the user "this push will give you a new preview URL" — it won't, the URL is stable per project now.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rush-ai",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Rush CLI - Command-line interface for the Rush AI platform",
   "private": false,
   "type": "module",

package/skills/README.md

@@ -16,7 +16,7 @@ Pick the guide that matches the situation:
   → Read [`push-local-project.md`](./push-local-project.md). Typical trigger: "同步一下 pod", "我本地改了代码推到 rush", "put the latest commits on the preview URL". `task push` does git push + pod sync/pull + Vite HMR — it does **not** create projects. (Journey J-2.)
 
 - **The user has a local project that needs its own database and/or OSS storage on Rush — not just a preview.**
-  → ⚠️ **Currently not recommended.** The `task link` path is blocked by #1147 (GitLab deploy-token scope rejected). For now, route these users to [`hand-off.md`](./hand-off.md) — ask them to describe the site (or attach files) and let `task create -a web-builder` rebuild it from scratch. Do not invoke `task link`; it will 502 at the finalize step. (Journey J-3 is paused.)
+  → Read [`project-setup.md`](./project-setup.md). Typical trigger: "把这个项目接入 Rush，要带数据库", "this repo uses Supabase / file uploads, set it up on Rush". `task link --db --oss` provisions the pod + DB + storage endpoint and emits an agent handoff. (Journey J-3.)
 
 - **The user has an existing web-builder project and wants to publish it to production / a custom domain.**
   → Read [`deploy-to-prod.md`](./deploy-to-prod.md). Typical trigger: "把这个站上线", "换成 my-app.rush.zhenguanyu.com", "deploy to prod". Works only for web-builder projects with a non-null template. (Journey J-4.)
@@ -29,8 +29,6 @@ Pick the guide that matches the situation:
 
 `hand-off.md` vs `push-local-project.md`: hand-off is **"let Rush create a new project from my prompt"**; push-local-project is **"sync my already-existing Rush project's local commits back to the pod preview"**. Heuristic: check `git -C . config --get remote.origin.url`. If origin is `gitlab-ee.zhenguanyu.com/rush/dev/<id>` (or `.rush/env.md` exists with a `PROJECT_ID`), the user is inside a Rush project — lean push. If there's no Rush identity on disk, lean hand-off.
 
-Note on the retired `project-setup` skill: previous versions shipped a `project-setup.md` that documented `task link --db --oss`. It has been removed from this package because the `task link` path is currently blocked (#1147 — GitLab deploy-token scope rejected). Until it's unblocked, route any "set this project up with its own DB / OSS on Rush" ask to [`hand-off.md`](./hand-off.md) and let `task create -a web-builder` rebuild the project from scratch. `task push` (this skill family) only syncs existing Rush projects; it does not provision.
-
 Still unsure? Run `npx rush-ai agent list` first — seeing the available agents usually makes the decision obvious.
 
 ## Cheat sheet

package/skills/deploy-to-prod.md

@@ -15,12 +15,11 @@ Triggers (not exhaustive — use judgement):
 Do NOT use this skill for:
 
 - **"Build me a new site from a prompt."** → No project exists yet. Use [`hand-off.md`](./hand-off.md) first; come back here after the project is ready.
-- **"Sync my local Rush project back to the pod (preview URL)."** → That's the J-2 sync path now; use [`push-local-project.md`](./push-local-project.md) (`task push`). `task push` does **not** create new projects — it syncs an existing one — so it does not produce fresh `template = null` projects anymore (see the banner below for how this differs from the old flow).
+- **"Sync my local Rush project back to the pod (preview URL)."** → That's the J-2 sync path; use [`push-local-project.md`](./push-local-project.md) (`task push`). `task push` does **not** create new projects — it only syncs commits onto an existing one.
+- **"Wire my non-Rush local repo into Rush with DB / OSS, then publish to a custom domain."** → Two skills, in order: first [`project-setup.md`](./project-setup.md) (`task link --db --oss`) to provision; **but note** `task link` projects have `template = null` and currently CANNOT flow through `task deploy` (epic #1096 Phase 2 — not shipped). For a custom-domain publish today, the project must originate from `task create -a web-builder`, not `task link`.
 - **Next.js production database provisioning** — `task deploy` only *checks* the prod DB exists (for nextjs templates); creating it is done in the Web UI.
 - **Rolling back a deploy.** There is no `rush-ai task rollback`; redeploy an earlier version via `--version <hash>` (see Playbook step 2).
 
-> ⚠️ **"将本地非 Rush 项目接入 Rush 再发 prod"暂不可用**: `task link` 的 GitLab deploy-token 步骤当前被 #1147 block。如果用户的项目不是从 Rush GitLab clone 出来的（且他们需要 DB/OSS），暂时请引导他们走 [`hand-off.md`](./hand-off.md) 重新起一个 `task create -a web-builder` 项目，而不是 `task link` 再 `task deploy`——后者目前会在 finalize 阶段 502。
-
 ## Decision
 
 Users often conflate three different operations. Use this table before any command runs:
@@ -30,7 +29,7 @@ Users often conflate three different operations. Use this table before any comma
 | User has a web-builder project (has `template`, `agent = web-builder`), wants a production / custom-domain URL | **this skill** (`task deploy <id>`) |
 | User is inside a Rush project working tree and wants the pod preview URL to catch up with local commits | [`push-local-project.md`](./push-local-project.md) (`task push` — sync only, no deploy) |
 | User wants to generate a brand-new site from a prompt | [`hand-off.md`](./hand-off.md) (`task create -a web-builder`) |
-| User wants to "deploy" a `task link` project (template = null) to a custom domain | **Not supported today.** `task link` itself is currently blocked by #1147 — see the banner above. |
+| User wants to "deploy" a `task link` project (template = null) to a custom domain | **Not supported today.** `task link` produces `template = null`; the conversion-to-template flow is epic #1096 Phase 2, not shipped. Use `task create -a web-builder` if a custom-domain publish is the end goal. |
 
 Fast sanity check before invoking any command in this skill:
 
@@ -139,7 +138,7 @@ Common failure paths to surface verbatim to the user:
 
 - `No versions yet. Send a message first.` → step 3 was skipped or the project has no builds.
 - `Build artifacts missing for commit <short>. Send a new message to rebuild.` → non-nextjs only. The OSS-backed build for that commit was never produced (or was cleaned up). Tell the user to `task send <id>` to trigger a rebuild.
-- `Production database not created. Open Web UI to create.` → nextjs-only preflight. The CLI cannot create the prod DB; the user must click through the Web UI.
+- `Required database is not configured. Open the Web UI to provision it before deploying.` → nextjs-only preflight. The CLI cannot create the required database; the user must click through the Web UI.
 - `409 Conflict` on the publish call → TOCTOU: someone else grabbed the prefix between step 4 and step 5. Loop back to step 4 with a new prefix.
 - SSE "Deployment stream disconnected unexpectedly" → nextjs publish-pod stream dropped mid-flight. Do NOT retry automatically; tell the user, let them retry manually.
 
@@ -161,13 +160,13 @@ To deploy a different branch/version to the **same** domain: `--version <otherHa
 
 ## Limitations
 
-- **Only web-builder projects with a non-null `template`.** `task deploy` refuses non-web-builder agents and `template = null` projects. Historically `task link` produced `template = null` projects; note that `task link` itself is currently blocked (#1147), so the more likely failing case today is a pre-existing `task link`-produced project in the user's history. (A "convert a non-template project into a template-backed project" flow is planned but **not shipped** — don't promise it.)
+- **Only web-builder projects with a non-null `template`.** `task deploy` refuses non-web-builder agents and `template = null` projects. `task link`-produced projects have `template = null` and CANNOT flow through `task deploy` — for custom-domain publishes the user must start from `task create -a web-builder`. (A "convert a non-template project into a template-backed project" flow is planned as epic #1096 Phase 2 but **not shipped** — don't promise it.)
 - **Next.js (`template = nextjs-fullstack`) forces `--env production`.** The publish-pod endpoint is server-hardcoded to `online`. `--env test` is rejected with a clear error. Non-nextjs templates support both `test` and `production`.
-- **Next.js also requires a provisioned production database.** If `hasProduction === false` the CLI aborts with `Production database not created. Open Web UI to create.` — this is **not** something the CLI can fix; the user must create it via the Web UI.
+- **Next.js also requires a provisioned database for the selected production source.** If `hasSelectedDatabase === false` the CLI aborts with `Required database is not configured. Open the Web UI to provision it before deploying.` — this is **not** something the CLI can fix; the user must create it via the Web UI.
 - **Domain prefix is global across Rush.** If someone else registered `my-app`, you can't have it. Use `task domain check` before deploy.
 - **No automatic rollback.** To "roll back," deploy an earlier `--version <hash>`. There is no `task deploy --rollback`.
 - **No retry on SSE stream drop (nextjs).** Publish-pod is a side-effecting POST; if the stream drops before a terminal event the CLI fails with `Deployment stream disconnected unexpectedly`. **Do not** re-invoke `task deploy` reflexively — re-posting can start a duplicate publish. Tell the user to check the Web UI / `task versions <id>` to see whether the deploy actually landed before retrying.
-- **`--yes` skips the confirmation prompt but not gating.** All preflight checks (web-builder gate, version list, build-check / has-production, domain check) still run. It only bypasses the interactive "proceed? y/n" prompt.
+- **`--yes` skips the confirmation prompt but not gating.** All preflight checks (web-builder gate, version list, build-check / database availability, domain check) still run. It only bypasses the interactive "proceed? y/n" prompt.
 
 ## Anti-patterns
 

package/skills/hand-off.md

@@ -18,8 +18,7 @@ Do NOT use this skill for:
 - The user already has a **Rush** project checked out locally and wants to sync local commits back to the pod — use [`push-local-project.md`](./push-local-project.md) (`task push`) instead of creating a new task from scratch.
 - The user already has a web-builder project and wants to publish it to prod / a custom domain — use [`deploy-to-prod.md`](./deploy-to-prod.md) (`task deploy`), not a new hand-off.
 - The user wants text / analysis / structured output (no preview URL) — use [`general-task.md`](./general-task.md) with `-a rush`.
-
-> ⚠️ **"接入非 Rush 本地项目"暂不可用**: `task link`（原 `task init`）的 GitLab deploy-token 步骤当前被 #1147 block（目标实例拒绝 `write_repository` scope）。如果用户有一个本地项目（非 rush 源）想接入 Rush——包括需要 DB / OSS 的 J-3 场景——暂时请走 `task create -a web-builder`（本 skill）从 prompt / 文件重建，不要引导用户去 `task link`。
+- The user has a local project (non-Rush) that needs its own database and/or OSS storage on Rush — use [`project-setup.md`](./project-setup.md) (`task link --db --oss`).
 
 ## Decision: which agent?