From 9adf2d0aba39d0e104dccaa7ed709656cf0066d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8C=85=E5=91=A8=E6=B6=9B?= Date: Fri, 17 Jul 2026 08:49:23 -0700 Subject: [PATCH] docs: remove stray -- from fresh-backend dev commands (#2801) pnpm passes the -- separator through to the script verbatim, so `pnpm dev -- --fresh -p ` reaches the CLI as positional args and exits with "Unexpected arguments" before binding the port. Drop the -- from all documented commands and fix the AGENTS.md note that claimed flags after -- are forwarded. Fixes #2801 Co-Authored-By: Claude Fable 5 --- AGENTS.md | 8 ++++---- content/docs/deployment/index.mdx | 2 +- content/docs/deployment/single-project-mode.mdx | 2 +- docs/adr/0015-external-datasource-federation.md | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e2f54c12f8..6477a822da 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,14 +28,14 @@ pnpm docs:dev # docs site | Scenario | Command | Notes | |:---|:---|:---| | **Frontend debug** (UI in `../objectui` calls backend) | `PORT=3000 pnpm dev` | `pnpm dev` = the **showcase** kitchen-sink app (default; best for exercising the platform). Port **must** be 3000 (UI hard-wired); persistent state; leave running. For the minimal CRM app instead: `PORT=3000 pnpm dev:crm`. | -| **Backend-only debug** | `pnpm dev -- --fresh -p ` | Random high port; ephemeral tempdir; **you must kill it** when done | +| **Backend-only debug** | `pnpm dev --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. -Rules: never run two backends on port 3000; for backend tasks pick a random port and tear it down; **never kill a server you didn't start** (other agents/the user may be using it — see Multi-agent discipline §8); always use a `pnpm dev`/`dev:crm`/`dev:showcase` script (flags after `--` are forwarded), not raw `pnpm --filter`. +Rules: never run two backends on port 3000; for backend tasks pick a random port and tear it down; **never kill a server you didn't start** (other agents/the user may be using it — see Multi-agent discipline §8); always use a `pnpm dev`/`dev:crm`/`dev:showcase` script (flags are forwarded as-is — no `--` separator, pnpm passes it through and the CLI rejects it), not raw `pnpm --filter`. ```bash -pnpm dev:crm -- --fresh -p 38421 # start; debug via curl +pnpm dev:crm --fresh -p 38421 # start; debug via curl kill $(lsof -ti tcp:38421) # tear down — tempdir auto-deletes ``` @@ -113,7 +113,7 @@ own worktree, operate defensively: 8. **Testing needs a server? Start your own temporary one — never stop someone else's.** A running dev server you didn't start probably belongs to another agent or the user; killing it (or its port) breaks their in-flight work. Spin - up your own instance on a random high port (`pnpm dev -- --fresh -p `) + up your own instance on a random high port (`pnpm dev --fresh -p `) and **shut it down yourself when the task is done** (`kill $(lsof -ti tcp:)`). Don't leave orphan servers behind. diff --git a/content/docs/deployment/index.mdx b/content/docs/deployment/index.mdx index 64cc9e1856..7cc753bd5c 100644 --- a/content/docs/deployment/index.mdx +++ b/content/docs/deployment/index.mdx @@ -24,7 +24,7 @@ Use the repo scripts for framework development: ```bash OS_PORT=3000 pnpm dev -pnpm dev:crm -- --fresh -p 38421 +pnpm dev:crm --fresh -p 38421 pnpm docs:dev ``` diff --git a/content/docs/deployment/single-project-mode.mdx b/content/docs/deployment/single-project-mode.mdx index 3239ea550b..c96d83f103 100644 --- a/content/docs/deployment/single-project-mode.mdx +++ b/content/docs/deployment/single-project-mode.mdx @@ -64,7 +64,7 @@ From the framework repo: OS_PORT=3000 pnpm dev # showcase example, persistent state, console at /_console -pnpm dev:crm -- --fresh -p 38421 +pnpm dev:crm --fresh -p 38421 # minimal CRM example with an ephemeral tempdir ``` diff --git a/docs/adr/0015-external-datasource-federation.md b/docs/adr/0015-external-datasource-federation.md index f9f0e879d1..afe1b015e5 100644 --- a/docs/adr/0015-external-datasource-federation.md +++ b/docs/adr/0015-external-datasource-federation.md @@ -639,7 +639,7 @@ export default defineObject({ os datasource validate warehouse # ✓ wh_order matches warehouse.mart.fact_orders (5/14 mapped, 9 unmapped — ok) -pnpm dev:crm -- --fresh -p 38421 +pnpm dev:crm --fresh -p 38421 # [info] external-validation: 1 datasource, 1 object, 0 mismatches ```