procdeck 1.1.0 → 2.0.0-rc.1

package/CHANGELOG.md

@@ -0,0 +1,277 @@
+# procdeck
+
+## 2.0.0
+
+### Major Changes
+
+- procdeck is one native binary now — rewritten in Go, the web UI embedded.
+  `npx procdeck` and `pnpm add -D procdeck` keep working: the npm package is a
+  small launcher, and the binary for your machine arrives as an optional
+  dependency (`@procdeck/<os>-<arch>`), with no install scripts. Node is no
+  longer needed to run procdeck. Outside npm there is a Homebrew tap, an
+  `install.sh`, and a tarball, `.deb` or `.rpm` per platform on every GitHub
+  release; `go install github.com/kondaurovDev/procdeck@latest` builds it from
+  source.
+
+  Breaking, against what 1.0 promised:
+
+  - **Configs are JSON** — `procdeck.config.json`, or `procdeck.config.jsonc`
+    with comments and trailing commas. A `procdeck.config.ts` / `.js` is
+    reported with a pointer to move it; `defineConfig` is gone with it.
+  - **Unknown config keys are errors**, instead of being silently ignored — a
+    typo like `"need"` no longer quietly does nothing.
+  - **Regexes are RE2** (`alerts`, `preflight.expect`, `--grep`, `--path`,
+    `--pattern`): no lookaround or backreferences, and linear time on any
+    output.
+  - **MCP tool problems** (no deck, unknown proc) come back as tool errors
+    (`isError`) rather than `{error}` values; read-only tools are annotated as
+    such.
+  - The global `--log-level` and `--completions` flags are gone; `procdeck
+completion <shell>` prints completions.
+
+### Minor Changes
+
+- `envFile` (one path or a list) layers dotenv files under every proc's `env`
+  and every preflight. The files are read at each spawn, so a refreshed `.env`
+  reaches a proc on its next restart — no deck restart, no
+  `node --env-file` wrapper.
+- `procdeck logs <proc> -f` follows a proc's output (it used to follow only
+  `--self`).
+- A detached deck's own log rotates past 4 MB instead of growing forever.
+
+### Patch Changes
+
+- The HTTP observer forwards standard proxy headers: `x-forwarded-host` carries
+  the original Host (an outer proxy's value wins), so frameworks that CSRF-check
+  Origin against it — Next.js Server Actions — accept mutating requests;
+  `x-forwarded-proto` and `x-forwarded-for` are set too. A client abort cancels
+  the upstream request, and an upstream dying mid-body cuts the client
+  connection instead of hanging it or appending an error note.
+- A relative `cwd` resolves against the config's directory, also for
+  `up --fg` from a subdirectory.
+- A `\r\n` split across two reads of a process's output no longer loses the
+  line.
+- Start/stop/restart of an unknown proc answers 404 with a message, not 500.
+- A proc's `cmd` is looked up in the proc's own `PATH`, and `PROCDECK_DETACHED`
+  no longer leaks into proc environments.
+- A preflight that times out is killed with its whole process group.
+- Port detection runs one `ps` and one `lsof` per poll for the whole deck,
+  instead of a pair per proc.
+
+## 1.1.1
+
+### Patch Changes
+
+- c1a0400: HTTP observer forwards standard proxy headers and propagates connection failures faithfully:
+
+  - `x-forwarded-host` now carries the original Host (an outer proxy's value wins), so frameworks that CSRF-check Origin against the forwarded host — Next.js Server Actions — no longer reject mutating requests. `x-forwarded-proto` and `x-forwarded-for` are set too.
+  - A client abort (closed tab, cancelled fetch) now destroys the upstream request instead of letting it stream to completion unseen.
+  - An upstream dying mid-body truncates the client response by cutting the connection, instead of hanging the client or corrupting the payload with an appended error note.
+
+## 1.1.0
+
+### Minor Changes
+
+- dace5bb: A proc can pin its assigned `${port}` to a fixed public number: `port: 8787`
+  on the spec. The public side stays exactly that number — dotenv files, mobile
+  simulators and teammates' scripts keep their hardcoded `localhost:8787` —
+  while an observed proc still binds a hidden internal port behind the HTTP
+  observer, so the traffic gets captured with no wiring changes anywhere.
+  Conflicting pins (duplicate, on the UI's port, or on a proc that never uses
+  `${port}`) are config errors; a pin whose port is already taken parks just
+  that proc in `blocked` — naming the port and the likely holder — while the
+  rest of the deck runs, and Start retries the bind. A pinned proc with no
+  `url` also gets its UI link derived from the pin.
+
+## 1.0.0
+
+### Major Changes
+
+- 2364ad0: procdeck 1.0.0. Nothing breaks in this release — the version says the surface
+  is settled and will not move under you without a major bump.
+
+  What 1.0 promises to keep stable:
+
+  - **The config**, both formats: every field of the schema (and therefore
+    `schema.json`), the `${port}` / `${port:id}` templating, `needs` /
+    `readyWhen` readiness, `preflight`, `alerts`, `observe`, and the
+    `defineConfig` export.
+  - **The CLI**: the verbs (`up`, `down`, `restart`, `status`, `ls`, `open`,
+    `init`, `logs`, `mark`, `wait-for`, `errors`, `http`, `agents`, `mcp`),
+    their flags, and the shape of every `--json` payload. `wait-for` keeps exit
+    2 for a timeout.
+  - **The MCP tools**: names and parameters of `deck_status`, `get_logs`,
+    `get_http`, `get_errors`, `set_mark`, `wait_for`, `timeline`, and the
+    `--mutations` trio.
+  - **The addresses**: `<id>.localhost:<ui-port>` for every proc, the UI on
+    4820 by default, loopback-only unless `host` says otherwise.
+
+  Internals stay internal: the deck's HTTP API, the registry files under
+  `~/.procdeck/`, the SSE event shapes and everything under `src/` are free to
+  change.
+
+  The readme is now the pitch and the docs live in `docs/` — config reference,
+  the agent harness, the traffic observer and the architecture notes.
+
+### Minor Changes
+
+- 6ef989d: `procdeck restart --all` restarts every deck on this machine — stop, then detach again
+  from each deck's own registry entry (foreground decks are skipped). The version a deck
+  actually runs now shows in `status`, `ls` and the UI's deck switcher, and `status`/`up`
+  say so out loud when it differs from the CLI — the answer to "did my update reach this
+  deck?".
+
+## 0.5.0
+
+### Minor Changes
+
+- 10b557f: procdeck is now a harness for coding agents, not just a dashboard for humans.
+  New CLI verbs, all bounded and `--json`-able: `status --json` grows an
+  `attention` list (crashed / blocked / alerting procs with reasons — the
+  cheapest first question); `logs [proc]` returns pane output as plain
+  timestamped lines (ANSI stripped, `\r` progress bars keep only their final
+  state), filterable with `--grep`, `--since`, `--lines` — no proc means every
+  proc interleaved with `[id]` prefixes, and the old daemon-log behaviour moved
+  to `logs --self [-f]`; `mark [name]` drops a named marker in every proc's
+  stream and `--since-mark` shows only what happened after it — the verify
+  loop (mark → edit → restart → check) in four commands; `wait-for <proc>
+[--pattern RE]` blocks until a listening port or a matching line, failing
+  fast with the log tail if the proc crashes instead (exit 2 on timeout);
+  `errors [proc]` parses stack traces out of recent output and deduplicates
+  them by signature ("same TypeError, 41×, last 3s ago"); `restart <proc>`
+  restarts a single process. `procdeck mcp` serves the same verbs over MCP
+  (stdio) — `claude mcp add procdeck -- procdeck mcp` once, globally, and the
+  instance registry finds the right deck per project; read-only by default,
+  `--mutations` adds restart/stop/start, plus `since_last` cursors and a
+  `timeline` tool. `procdeck agents` (and `procdeck init`) plant the discovery:
+  a `## procdeck` section in CLAUDE.md / AGENTS.md and a Claude Code skill
+  teaching the loop.
+- 10b557f: procdeck sees the traffic now, not just the logs. Procs that use `${port}`
+  get an HTTP observer interposed on their assigned port: the proc binds a
+  hidden internal port, procdeck listens on the public one and forwards — so
+  requests between processes (`${port:api}`) and into them are captured
+  transparently, statuses and bodies included, with zero app changes
+  (`"observe": false` opts a proc out; the `*.localhost` proxy captures for
+  opted-out procs). WebSocket connections are captured per-message with
+  direction and text — compression is stripped at the handshake so frames stay
+  readable. Bodies are text-only and truncated (16 KB); `authorization`,
+  `cookie` and friends are redacted before anything is stored. Three surfaces
+  over the same per-proc rings: `procdeck http [proc] [--status 5xx|422|error]
+[--path RE] [--since-mark] [--ws] [--body] [--digest] [--json]` — `--digest`
+  groups 4xx/5xx by route with path params collapsed (`/users/:id`); a
+  `get_http` MCP tool with `since_last` cursors (and `timeline` now carries
+  the window's exchanges); and a traffic view in the UI — the ⇄ position of
+  the layout switch — with kind/proc/errors filters, click-to-expand bodies,
+  pause and clear. Marks span both streams, so mark → act →
+  `http --since-mark` shows exactly which requests a change caused and what
+  they returned.
+
+## 0.4.0
+
+### Minor Changes
+
+- 8e4b627: procdeck runs in the background now. `procdeck up` (and bare `procdeck`) starts the
+  deck detached, opens the UI and returns — no terminal tab kept hostage; `up --fg` is
+  the old foreground mode. New commands, all working from anywhere inside the project:
+  `down` (terminates every process tree), `restart`, `status`, `ls` (every running deck
+  on the machine), `open` and `logs [-f]`. Running decks register in
+  `~/.procdeck/instances/` (stale entries pruned by pid; `PROCDECK_HOME` relocates it);
+  a detached deck's own output goes to `~/.procdeck/logs/`. `up` refuses a port already
+  held by another deck — naming it — or simply busy, before anything spawns; a bad
+  config is reported in the terminal, not in a log file. In the UI: ⏻ shuts the deck
+  down (with a confirm), the page says so instead of "reconnecting" and revives itself
+  when `procdeck up` runs again; the deck name in the bar lists the other running decks
+  as links. The CLI moved to `effect/unstable/cli` — `--help` per command, shell
+  completions via `--completions`.
+- f2abc61: Three things for the first real release. **Loopback only:** the server binds
+  `127.0.0.1` by default — the UI types into real terminals, so it is not something to
+  put on the LAN by accident; `"host": "0.0.0.0"` in the config opens it up for
+  devcontainers and VMs. **Per-proc backlog:** each proc keeps its last 256 KB of output
+  and a new tab gets every pane's history plus a `synced` marker before live events — a
+  chatty ticker can no longer evict a quiet server's startup lines, a deck that has run
+  for days still opens with every pane populated, the UI knows exactly which chunks are
+  news, and a reconnect replays into freshly reset panes instead of appending history to
+  itself. **`procdeck init`:** writes a first `procdeck.config.json` from what is already there —
+  a Procfile, workspace packages with `dev` scripts (via the package manager your lockfile
+  points at), plain `backend/` + `frontend/` subdirectories (each its own package.json or
+  a Django / Go / Rust / Rails / compose project, with `cwd` set), or the root itself.
+
+### Patch Changes
+
+- 9f944e5: The deck tells you when it needs you. Procs that crashed, are blocked on a preflight,
+  carry an alert or have unread error lines count into the tab title (`(2) garage ·
+procdeck`) and put a red dot on the favicon — visible from the tab strip and the Dock.
+  A bell in the global bar turns on system notifications: a crash, a block or a new alert
+  while the tab is hidden or the window unfocused shows one (click brings the deck back);
+  replayed history on reconnect never notifies. The bell state persists with the UI state;
+  the browser permission is asked for on the first click.
+- 1db7f78: Grid pinning. Pin a proc (📌 in its pane header or sidebar row, ⌥P on the active one) and
+  the grid shows only pinned procs; the rest collapse into a tray strip under the tiles —
+  status dot, id, badges — where a click peeks at one and the pin puts it back. Nothing
+  pinned = everyone tiled, as before. ⌥Z zooms the active tile in and out of single. The
+  grid now sizes its columns from the tile count (near-square, at most 4) so the deck fits
+  the screen when it can and scrolls only when tiles would drop under 180 px. Pins persist
+  with the rest of the UI state.
+- e90a08c: Polish before publishing, part one.
+
+  - URLs in pane output are clickable (`Local: http://localhost:5173/` from every dev
+    server opens in a new tab).
+  - Exit status reads like a human wrote it: `exit 1 · 2m ago`, `killed (SIGTERM) · 5s ago`
+    — signal names instead of numbers, and no more `signal 0` on a plain non-zero exit.
+    Running procs that were respawned show a restart count (`↻3`), so crash loops are
+    visible from the status line. The sidebar shows the same exit summary where uptime sits
+    while running.
+  - Grid tile headers keep the `*.localhost` address whole instead of clipping it to `:61`:
+    compact tiles show only the primary address (raw ports in its tooltip) and the status
+    text is what gives way first.
+  - The assigned port no longer also counts as "internal" when it lands in the ephemeral
+    range.
+
+- a85d537: Light theme. A System · Light · Dark switch in the global bar; System follows the OS
+  (`prefers-color-scheme`) and tracks it live. The terminals switch palette too — light gets
+  its own ANSI set (GitHub Light), since xterm's defaults are unreadable on white. The choice
+  is stored with the rest of the UI state and painted before the first frame, so there is
+  no flash on reload.
+- 512e814: The UI remembers itself across reloads, and says when it has lost the server.
+
+  Layout (single/grid) and the selected pane are kept in localStorage — per origin, so per
+  deck — and restored on the next load; a stored pane that is no longer in the config falls
+  back to the first one. While the event stream is down (a `procdeck restart`, a killed
+  server) a "reconnecting" banner sits over the panes instead of the UI silently showing
+  stale state; when the stream is back the proc snapshot is refetched so statuses that
+  changed in the meantime catch up. A stream the browser gave up on (server answered with
+  something other than an event stream) is retried every 2 s.
+
+## 0.3.0
+
+### Minor Changes
+
+- a1ced2e: Cut the install from 116 MB to 1.8 MB, and remove every reason for it to fail.
+
+  `node-pty` is replaced by `@lydell/node-pty` — the same upstream sources and the same API,
+  but the binaries ship as per-platform optional dependencies instead of one tarball carrying
+  every platform's prebuilds. Upstream runs an install script and has no Linux prebuild at
+  all, so Linux users needed a C++ toolchain and pnpm ≥ 10 / Bun users needed
+  `pnpm approve-builds` (or `trustedDependencies`) on every platform or spawning failed at
+  runtime. The replacement runs no install script and compiles nothing, anywhere — which also
+  retires the startup hack that repaired the darwin `spawn-helper` execute bit.
+
+  `effect` is no longer installed either: it is bundled into the CLI, where tree-shaking takes
+  it from 48 MB on disk to under 1 MB of shipped code. The package's public entry point
+  (`defineConfig` and the config types) is now a standalone module with no effect types in its
+  declarations, so a `procdeck.config.ts` typechecks against a package that has none of
+  procdeck's own dependencies installed.
+
+## 0.2.0
+
+### Minor Changes
+
+- 212de8d: Accept `procdeck.config.json` next to the TypeScript config, validated by the same schema.
+  A JSON deck needs nothing from the project's toolchain — no TypeScript, and procdeck itself
+  does not have to be a dependency, so `npx procdeck` works in any repo. Point `$schema` at
+  `https://unpkg.com/procdeck/schema.json` (generated from the Effect schema at build time and
+  shipped with the package) for completion and validation in the editor.
+
+  Started without an argument, the CLI now looks for `procdeck.config.json`, `.ts`, `.js` and
+  `.mjs` in that order, and reports a missing or unreadable config against the file instead of
+  crashing. `port` is validated as an integer in 1–65535.

package/bin/procdeck.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+"use strict"
+
+// procdeck's npm entry. The binary for this machine ships as an optional
+// dependency — @procdeck/<os>-<arch> — so the package manager installs only
+// the one that fits, with no install scripts. This launcher finds it and runs
+// it with the same arguments, terminal and exit code.
+
+const { spawn } = require("node:child_process")
+
+const supported = ["darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64"]
+const target = `${process.platform}-${process.arch}`
+
+const fail = (message) => {
+  console.error(`procdeck: ${message}`)
+  process.exit(1)
+}
+
+const binary = () => {
+  // A binary built from source, for trying a change through this launcher.
+  if (process.env.PROCDECK_BINARY) return process.env.PROCDECK_BINARY
+  if (!supported.includes(target)) {
+    fail(`no binary for ${target} — supported: ${supported.join(", ")}`)
+  }
+  try {
+    return require.resolve(`@procdeck/${target}/bin/procdeck`)
+  } catch {
+    fail(
+      `@procdeck/${target} is missing — it carries the procdeck binary for this machine. ` +
+        "Reinstall without --no-optional / --omit=optional."
+    )
+  }
+}
+
+const child = spawn(binary(), process.argv.slice(2), { stdio: "inherit" })
+
+// Pass signals on rather than dying of them: the binary decides how to stop
+// (a deck tears its processes down first). A Ctrl-C reaches the binary from
+// the terminal as well; it reads a repeat within a moment as the same press.
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(signal, () => child.kill(signal))
+}
+
+child.on("error", (cause) => fail(cause.message))
+child.on("exit", (code, signal) => {
+  if (signal === null) process.exit(code ?? 1)
+  // Die of the same signal, so the caller sees what the binary saw.
+  process.removeAllListeners(signal)
+  process.kill(process.pid, signal)
+})

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "procdeck",
-  "version": "1.1.0",
-  "description": "Interactive dev-process multiplexer with a web UI: terminal panes in a browser tab, declarative dependencies, assigned ports and a *.localhost reverse proxy.",
+  "version": "2.0.0-rc.1",
+  "description": "Dev-process multiplexer with a web UI: terminal panes in a browser tab, declarative dependencies, assigned ports, a *.localhost proxy and captured HTTP traffic. One native binary.",
   "keywords": [
     "cli",
     "dev-server",
@@ -22,56 +22,23 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/kondaurovDev/procdeck",
-    "directory": "packages/procdeck"
+    "directory": "npm/procdeck"
   },
   "bin": {
-    "procdeck": "./dist/cli.js"
+    "procdeck": "bin/procdeck.js"
   },
   "files": [
-    "dist",
+    "bin",
     "schema.json",
-    "ui/dist"
+    "CHANGELOG.md"
   ],
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./dist/public.d.ts",
-      "import": "./dist/public.js"
-    }
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@lydell/node-pty": "1.2.0-beta.15"
-  },
-  "devDependencies": {
-    "@effect/platform-browser": "4.0.0-beta.106",
-    "@effect/platform-node-shared": "4.0.0-beta.106",
-    "@types/node": "^22.10.1",
-    "@xterm/addon-fit": "^0.11.0",
-    "@xterm/addon-search": "^0.16.0",
-    "@xterm/addon-web-links": "^0.12.0",
-    "@xterm/xterm": "^6.0.0",
-    "effect": "4.0.0-beta.106",
-    "foldkit": "^0.141.2",
-    "tsup": "^8.5.1",
-    "typescript": "^7.0.2",
-    "vite": "^6.2.0",
-    "vitest": "^3.2.4"
-  },
   "engines": {
-    "node": ">=22"
+    "node": ">=18"
   },
-  "scripts": {
-    "ui:dev": "vite ui",
-    "build": "pnpm run build:meta && pnpm run build:schema && pnpm run build:ui && pnpm run build:js && pnpm run build:types",
-    "build:meta": "cp ../../readme.md ../../license .",
-    "build:schema": "node scripts/gen-schema.ts",
-    "build:ui": "vite build ui",
-    "build:js": "tsup",
-    "build:types": "tsc -p tsconfig.build.json",
-    "check:types": "tsc --noEmit && tsc -p ui --noEmit",
-    "test": "vitest run"
+  "optionalDependencies": {
+    "@procdeck/linux-arm64": "2.0.0-rc.1",
+    "@procdeck/linux-x64": "2.0.0-rc.1",
+    "@procdeck/darwin-x64": "2.0.0-rc.1",
+    "@procdeck/darwin-arm64": "2.0.0-rc.1"
   }
-}
+}

package/readme.md

@@ -7,7 +7,7 @@ Run your whole dev stack with one command — and actually see what it's doing.
 
 ![The example stack in procdeck: six processes tiled, every pane a live terminal, every service on its own *.localhost address, the flaky one flagged](https://raw.githubusercontent.com/kondaurovDev/procdeck/main/docs/screenshot.webp)
 
-procdeck is four tools in one ~2 MB package — the process runner, the port
+procdeck is four tools in one binary — the process runner, the port
 allocator, the log viewer and the network tab of your dev environment:
 
 - **Runs everything.** Every proc is a real terminal in a browser tab — and
@@ -28,20 +28,29 @@ npx procdeck          # starts the deck in the background and opens the UI
 ```
 
 The UI opens at <http://localhost:4820> and your terminal is free again.
-`procdeck down` stops everything. Requires **Node ≥ 22**, macOS or Linux.
+`procdeck down` stops everything. macOS or Linux.
 
-Prefer it in the project (and you do, if you want the config in TypeScript):
+## Install
+
+procdeck is a single native binary with the web UI inside — nothing else to
+install, no runtime to match. Pick the channel that fits:
 
 ```sh
-pnpm add -D procdeck      # npm i -D procdeck · bun add -d procdeck
+brew install kondaurovDev/tap/procdeck    # macOS, with shell completions
+curl -fsSL https://raw.githubusercontent.com/kondaurovDev/procdeck/main/install.sh | sh
+pnpm add -D procdeck    # npm i -D procdeck · bun add -d procdeck — pins the version for the whole team
+go install github.com/kondaurovDev/procdeck@latest
 ```
 
-> **Install footprint.** ~2 MB, one dependency. The server ships as a bundle,
-> so nothing but the PTY bindings is installed — and those are
-> [`@lydell/node-pty`](https://github.com/lydell/node-pty): the same sources as
-> [node-pty](https://github.com/microsoft/node-pty), as per-platform packages.
-> Nothing compiles and no install script runs, so there is no
-> `pnpm approve-builds` detour and no compiler needed on Linux.
+or a tarball, `.deb` or `.rpm` for your platform from the
+[releases](https://github.com/kondaurovDev/procdeck/releases). On Windows,
+install inside WSL.
+
+> **What npm installs.** A small launcher, plus exactly one
+> `@procdeck/<os>-<arch>` package with the binary for your machine — picked by
+> the package manager through `optionalDependencies`. No install script runs,
+> so there is no `pnpm approve-builds` detour and nothing compiles. Node runs
+> the launcher; the deck itself does not need it.
 
 ## What you get
 
@@ -157,31 +166,37 @@ for a devcontainer or a VM. No telemetry, no service worker.
 }
 ```
 
-JSON needs nothing from your toolchain — no TypeScript, and procdeck does not
-have to be a dependency. TypeScript configs buy comments and computed values:
+Comments and trailing commas are welcome — name the file
+`procdeck.config.jsonc` if your editor wants a hint. Unknown keys are errors,
+so a typo never silently does nothing. `"envFile": ".env"` hands every proc the
+variables of a dotenv file. Full field reference:
+[docs/config.md](https://github.com/kondaurovDev/procdeck/blob/main/docs/config.md).
+
+## Upgrading from 1.x
 
-```ts
-import { defineConfig } from "procdeck"
+2.0 is the same tool rewritten in Go — the CLI verbs, their flags and `--json`
+shapes, the MCP tools and the addresses stay. What changes:
 
-export default defineConfig({
-  procs: [{ id: "api", shell: "pnpm dev", env: { PORT: "${port}" } }]
-})
-```
+- **Configs are JSON.** A `procdeck.config.ts` becomes `procdeck.config.jsonc`:
+  quote the keys, drop the `import` and `defineConfig(…)`, keep the comments.
+- **Regexes are RE2** (Go's): no lookaround or backreferences.
+- **Unknown config keys are errors.**
+- **No `node --env-file` wrapper** needed — use `envFile` in the config.
 
-Both formats validate against the same schema. Full field reference:
-[docs/config.md](https://github.com/kondaurovDev/procdeck/blob/main/docs/config.md).
+A 1.x deck and the 2.0 CLI understand each other (same registry, same API), so
+`procdeck restart` moves a running deck over.
 
 ## Try the example
 
-In a clone of this repo:
+In a clone of this repo, with Go ≥ 1.26 and pnpm:
 
 ```sh
 pnpm install
-pnpm dev          # builds the UI, starts the example stack in the foreground
+pnpm dev          # builds the UI, embeds it, runs the example stack on the Go procdeck
 ```
 
-Then open <http://localhost:4820> for the panes, and
-<http://web.localhost:4820> / <http://api.localhost:4820> — the example's
+Then open <http://localhost:4840> for the panes, and
+<http://web.localhost:4840> / <http://api.localhost:4840> — the example's
 servers found each other, and their own ports, entirely through `${port}`
 templates. See [`example/`](https://github.com/kondaurovDev/procdeck/tree/main/example).
 
@@ -197,7 +212,7 @@ templates. See [`example/`](https://github.com/kondaurovDev/procdeck/tree/main/e
 
 ## Status
 
-**macOS and Linux.** Port discovery asks the OS through `pgrep` + `lsof`, and
+**macOS and Linux.** Port discovery asks the OS through `ps` + `lsof`, and
 a whole-tree restart signals the process group (`kill(-pid)`) — both POSIX.
 Windows works through WSL, not natively.