From 25993594a7c9fa4019a0d2f19b94b8d8383c234e Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Mon, 1 Jun 2026 13:11:05 +0800 Subject: [PATCH] docs(agents): document frontend dev loop (showcase backend on :3000, fast objectui dev server) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The AGENTS.md dev-server guidance was CRM-only. Add the showcase frontend-debug recipe (`PORT=3000 pnpm dev`) and document the fast iteration path against `../objectui` src — run objectui's own console dev server (:5180) whose /api proxy targets :3000 — alongside the existing commit→`objectui:refresh` loop. Clarifies that the backend-served `_console` is the published build, not src. Captures the topology that caused avoidable thrash debugging the showcase UI. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 83bfcdf5a..121657374 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,6 +21,7 @@ pnpm docs:dev # docs site | Scenario | Command | Notes | |:---|:---|:---| | **Frontend debug** (UI in `../objectui` calls backend) | `PORT=3000 pnpm dev:crm` | Port **must** be 3000 (UI hard-wired); persistent state; leave running | +| **Frontend debug (showcase)** | `PORT=3000 pnpm dev` | `pnpm dev` = the **showcase** example; same port-3000 rule. Use this (not `dev:crm`) when debugging showcase UI/automation | | **Backend-only debug** | `pnpm dev:crm -- --fresh -p ` | Random high port; ephemeral tempdir; **you must kill it** when done | `--fresh`: ephemeral tempdir (auto-deleted on exit) + `--seed-admin` (POSTs sign-up, prints creds — default `admin@objectos.ai` / `admin123`, override via `--admin-email`/`--admin-password`). The seeded admin is auto-promoted to **platform admin** (the system seed identity `usr_system` is skipped), so Setup/Studio are reachable on first login. @@ -38,6 +39,8 @@ This repo ships **backend only**. All Studio/Console UI work happens in `../obje Other scripts: `objectui:bump` (pull only), `objectui:build`, `objectui:clean`. ⚠️ Never hand-edit `packages/console/dist/` or `.cache/objectui-*/` — regenerated. +**Fast iteration on `../objectui` src (no commit/refresh loop):** run objectui's own console dev server — `cd ../objectui && pnpm --filter @object-ui/console dev` (Vite on **:5180**, HMR). Its `/api` proxy targets `DEV_PROXY_TARGET || http://localhost:3000`, so **run the backend you're testing on :3000** (`PORT=3000 pnpm dev` for showcase) and browse `:5180`. Note `:3001/_console` (or whatever the backend serves) is the **published** console, not your `../objectui` src — only `:5180` reflects local UI edits. See `../objectui/AGENTS.md` for the app-id / localStorage / auth gotchas. + --- ## Prime Directives