diff --git a/.devenv/README.md b/.devenv/README.md
new file mode 100644
index 0000000000..d56e327dd0
--- /dev/null
+++ b/.devenv/README.md
@@ -0,0 +1,133 @@
+# `.devenv/` — Per-Workspace AI-Client MCP Configs
+
+This directory carries the pieces needed to point an AI coding agent
+(currently Claude Code, opencode, VS Code Copilot, and the OpenAI Codex CLI)
+at the MCP servers running inside the parallel devenv instance the developer
+is currently working in. Every parallel workspace (`ws0`, `ws1`, …) has its
+own copy because the Penpot MCP and Serena MCP host ports are
+workspace-specific.
+
+## Layout
+
+```
+.devenv/
+  README.md
+  scripts/
+    merge-mcp-config.py    # generator helper invoked by manage.sh
+  shared/                  # committed; workspace-independent entries
+    claude-code.json       # Playwright — same for every workspace
+    opencode.json
+    vscode.json
+    codex.toml
+  templates/               # committed; entries with ${...} port placeholders
+    claude-code.json       # Penpot MCP, Serena MCP — port is the only diff
+    opencode.json
+    vscode.json
+    codex.toml
+  mcp/                     # gitignored; written by manage.sh per workspace
+    claude-code.json       # loaded via Claude Code's --mcp-config flag
+    opencode.json          # loaded via OPENCODE_CONFIG env var
+```
+
+One more file is generated outside `.devenv/`, in the directory VS Code itself
+auto-discovers (gitignored):
+
+```
+.vscode/mcp.json           # auto-loaded by GitHub Copilot in VS Code
+```
+
+Codex is the exception: it has no way to load an MCP config from an arbitrary
+path, and its only project-level config file (`.codex/config.toml`) is one a
+developer may already own. So we do **not** write a file for Codex at all —
+`start-coding-agent codex` injects our servers as `-c` command-line overrides
+built fresh from `shared/codex.toml` + `templates/codex.toml` at launch.
+
+* **`shared/`** holds MCP entries that don't depend on the workspace — the
+  browser-driving Playwright server today, plus any other workspace-independent
+  servers we add later. Same content in every workspace, so it's a static
+  checked-in file.
+* **`templates/`** holds the workspace-specific entries (Penpot MCP, Serena
+  MCP) with `${PENPOT_MCP_PORT}` and `${SERENA_MCP_PORT}` placeholders. The
+  placeholders are resolved per-workspace from the port-base constants in
+  `manage.sh`.
+* **`mcp/`** (Claude Code, opencode) is the result of merging `shared/` with
+  the port-substituted `templates/`. `manage.sh` writes these on every
+  `run-devenv-agentic` pass. Gitignored, dedicated paths with no developer
+  content — never edit by hand, your edits will be overwritten on the next
+  reconcile.
+* **`.vscode/mcp.json`** is the same merge, but written to the path VS Code
+  auto-discovers. Because on `ws0` that path *is* the live repo's own file, the
+  reconcile **deep-merges** into it: any servers you added yourself are kept,
+  and only the entries we manage (`penpot`, `serena-devenv`, `playwright`) are
+  (re)written to the current ports. On `ws1+` the file doesn't exist yet, so it
+  is created from scratch.
+* **`scripts/merge-mcp-config.py`** is the generator. Its `json` mode does the
+  JSON deep-merge (with `--merge-into-existing` for the VS Code path); its
+  `codex-args` mode prints the `-c` assignments for Codex. `manage.sh`'s
+  `_merge-mcp-config-json` helper is a thin shim over the former, and
+  `start-coding-agent` calls the latter directly. Run
+  `python3 .devenv/scripts/merge-mcp-config.py --help` for the CLI.
+
+## Launching a coding agent
+
+The easiest path is the wrapper command, which knows the right flags per
+client, `cd`'s into the target workspace, and refuses to launch unless the
+target instance is running and its MCP config has been generated:
+
+```bash
+# Default target is ws0 (the live repo).
+./manage.sh start-coding-agent claude               [...args to forward]
+./manage.sh start-coding-agent opencode             [...args to forward]
+./manage.sh start-coding-agent vscode               [...args to forward to 'code']
+./manage.sh start-coding-agent codex                [...args to forward]
+
+# Target a parallel workspace with --ws N. N is an integer (non-negative);
+# 'main', 'ws1' and similar spellings are rejected.
+./manage.sh start-coding-agent claude --ws 1
+./manage.sh start-coding-agent opencode --ws 2
+```
+
+Equivalents by hand (run from inside the workspace directory):
+
+```bash
+claude --mcp-config .devenv/mcp/claude-code.json
+OPENCODE_CONFIG=.devenv/mcp/opencode.json opencode
+code "$PWD"                  # VS Code auto-discovers .vscode/mcp.json
+# Codex: pass our servers as -c overrides (no config file is written).
+codex $(python3 .devenv/scripts/merge-mcp-config.py --format codex-args \
+          .devenv/shared/codex.toml .devenv/templates/codex.toml \
+          | sed 's/^/-c /')
+```
+
+`start-coding-agent codex` does the `-c` wiring for you (and resolves the
+workspace's ports first). Because our servers arrive as command-line
+overrides, no "trusted project" prompt is involved for them — that prompt only
+gates Codex's own `.codex/config.toml`, which we never write.
+
+## Overriding our entries
+
+Both the auto-discovered configs and the launcher-loaded configs sit *on top
+of* the developer's global config (with varying precedence rules). All four
+clients offer escape hatches for shadowing entries we ship:
+
+* **Claude Code** — `claude mcp add --scope local …` installs a private entry
+  that overrides the one in `mcp/claude-code.json`. Local scope wins.
+* **opencode** — drop an `opencode.json` at the repo root with the override
+  entries you need. opencode's precedence chain is *global → `OPENCODE_CONFIG`
+  → project*, so the project file always wins. The root `opencode.json` is
+  gitignored on purpose, since these overrides are personal.
+* **VS Code Copilot** — the reconcile deep-merges into `.vscode/mcp.json`, so
+  any servers you add there yourself are preserved (only `penpot`,
+  `serena-devenv` and `playwright` are rewritten). To shadow one of *ours*,
+  put an entry under the same name in your VS Code user-profile MCP config —
+  it is loaded alongside the workspace file and wins.
+* **Codex CLI** — our servers arrive as `-c` overrides, which are Codex's
+  highest-precedence layer, so they win over a same-named `[mcp_servers.<name>]`
+  in your `~/.codex/config.toml` or a project `.codex/config.toml`. To override
+  one of ours, append your own `-c` after the client name — extra args are
+  forwarded after ours and the later `-c` wins, e.g.
+  `./manage.sh start-coding-agent codex -- -c 'mcp_servers.penpot.url="…"'`.
+
+See `docs/technical-guide/developer/agentic-devenv.md` for the broader
+client-configuration story (browser remote debugging, AI-client config
+schemas, manual setup for unsupported clients).
diff --git a/.devenv/scripts/merge-mcp-config.py b/.devenv/scripts/merge-mcp-config.py
new file mode 100755
index 0000000000..ffa5d9a717
--- /dev/null
+++ b/.devenv/scripts/merge-mcp-config.py
@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""Combine a shared MCP-server config with a port-substituted template for one
+AI coding-agent client.
+
+Invoked per workspace by manage.sh's `write-instance-mcp-configs` (JSON
+clients) and by `start-coding-agent` (Codex). Each supported client ships a
+`.devenv/shared/<tool>.{json,toml}` (workspace-independent entries, e.g.
+Playwright) and a `.devenv/templates/<tool>.{json,toml}` (per-workspace entries
+with `${PENPOT_MCP_PORT}` / `${SERENA_MCP_PORT}` placeholders). This script
+combines the two for the target client.
+
+Two output modes are supported:
+
+  json         Deep-merge two JSON documents under a configurable top-level key
+               (`mcpServers` for Claude Code, `mcp` for opencode, `servers` for
+               VS Code Copilot) and write the result to <out>. Same-name
+               entries in the template override entries in shared. With
+               --merge-into-existing, any pre-existing <out> file is loaded as
+               the lowest-precedence layer first, so entries the developer
+               already had are preserved (ours win on name collision). This is
+               used for VS Code's auto-discovered `.vscode/mcp.json`, which on
+               ws0 IS the live repo's file and may hold the developer's own
+               servers; the Claude/opencode outputs live in a dedicated,
+               gitignored `.devenv/mcp/` path and are written without the flag
+               (a clean overwrite).
+
+  codex-args   Deep-merge the two TOML chunks and print one
+               `dotted.key=<toml-value>` assignment per line to stdout (no
+               <out> file). The caller wraps each line in a `codex -c` flag.
+               Codex has no way to load an MCP config from an arbitrary file
+               path (CODEX_HOME would relocate auth/history too), so rather than
+               writing the auto-discovered `.codex/config.toml` we inject our
+               servers as ephemeral per-invocation overrides. This never
+               touches the developer's project- or user-level Codex config.
+
+In both modes, `${VAR}` placeholders inside *either* chunk are resolved from
+the current environment (only template chunks carry placeholders in practice,
+but the substitution is uniform either way) using Python's
+`os.path.expandvars`. Undefined placeholders are left as `${VAR}` literal text
+-- callers (i.e. manage.sh) are responsible for exporting the variables before
+invoking the script.
+
+Usage:
+  merge-mcp-config.py --format json --key <key> [--merge-into-existing] \
+      <shared> <template> <out>
+  merge-mcp-config.py --format codex-args <shared> <template>
+
+Exit codes:
+  0  success
+  2  argparse error (missing required option, bad value, unreadable input)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import tomllib
+from pathlib import Path
+
+
+def merge_json(
+    shared_path: Path,
+    tpl_path: Path,
+    out_path: Path,
+    key: str,
+    merge_into_existing: bool,
+) -> None:
+    """Deep-merge JSON documents under a single top-level dict key into out.
+
+    Precedence (lowest to highest): an existing <out> file (only when
+    merge_into_existing is set), then shared, then the template. Entries under
+    `key` are merged by name, so the template wins on a name collision while
+    every other entry the lower layers contributed is kept. Top-level keys
+    other than `key` come from the existing file and shared (shared wins).
+    """
+    shared = json.loads(shared_path.read_text())
+    tpl = json.loads(os.path.expandvars(tpl_path.read_text()))
+
+    base: dict = {}
+    if merge_into_existing and out_path.exists():
+        base = json.loads(out_path.read_text())
+
+    merged: dict = {**base, **shared}
+    merged[key] = {**base.get(key, {}), **shared.get(key, {}), **tpl.get(key, {})}
+
+    out_path.write_text(json.dumps(merged, indent=2) + "\n")
+
+
+def _deep_merge(base: dict, overlay: dict) -> dict:
+    """Recursively merge overlay into base; overlay wins on scalar/list keys."""
+    out = dict(base)
+    for k, v in overlay.items():
+        if isinstance(out.get(k), dict) and isinstance(v, dict):
+            out[k] = _deep_merge(out[k], v)
+        else:
+            out[k] = v
+    return out
+
+
+def _toml_value(value: object) -> str:
+    """Serialize a scalar/list as a TOML literal for a `codex -c` value.
+
+    bool is checked before int because `isinstance(True, int)` is True. Strings
+    are emitted as JSON strings, which are valid TOML basic strings for the
+    ASCII values our configs carry (commands, args, URLs). Tables never reach
+    here -- they are flattened into dotted keys by _flatten.
+    """
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return repr(value)
+    if isinstance(value, str):
+        return json.dumps(value)
+    if isinstance(value, list):
+        return "[" + ", ".join(_toml_value(v) for v in value) + "]"
+    raise TypeError(f"unsupported TOML value type: {type(value).__name__}")
+
+
+_BARE_KEY = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def _key_segment(seg: str) -> str:
+    """A dotted-key segment: bare if TOML-safe, else a quoted key."""
+    return seg if _BARE_KEY.match(seg) else json.dumps(seg)
+
+
+def _flatten(obj: dict, prefix: list[str]):
+    """Yield (dotted-path-segments, leaf-value) for every non-table leaf.
+
+    Lists are leaves (TOML arrays), so we do not recurse into them; nested
+    tables (e.g. an `env` table) are flattened into further dotted keys.
+    """
+    for k, v in obj.items():
+        path = prefix + [k]
+        if isinstance(v, dict):
+            yield from _flatten(v, path)
+        else:
+            yield path, v
+
+
+def emit_codex_args(shared_path: Path, tpl_path: Path) -> None:
+    """Print `dotted.key=<toml-value>` lines from the merged TOML chunks."""
+    shared = tomllib.loads(os.path.expandvars(shared_path.read_text()))
+    tpl = tomllib.loads(os.path.expandvars(tpl_path.read_text()))
+    merged = _deep_merge(shared, tpl)
+    for path, value in _flatten(merged, []):
+        dotted = ".".join(_key_segment(s) for s in path)
+        sys.stdout.write(f"{dotted}={_toml_value(value)}\n")
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description=__doc__.split("\n\n", 1)[0],
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--format",
+        choices=("json", "codex-args"),
+        required=True,
+        help="Output mode: 'json' writes a merged file; 'codex-args' prints -c assignments.",
+    )
+    parser.add_argument(
+        "--key",
+        help="Top-level JSON key under which MCP entries live (required for --format json).",
+    )
+    parser.add_argument(
+        "--merge-into-existing",
+        action="store_true",
+        help="json only: layer the merge on top of an existing <out> file, "
+        "preserving entries already there (ours still win on name collision).",
+    )
+    parser.add_argument("shared", type=Path, help="Path to the shared chunk.")
+    parser.add_argument("template", type=Path, help="Path to the port-placeholder template chunk.")
+    parser.add_argument(
+        "out",
+        type=Path,
+        nargs="?",
+        help="Path the merged result is written to (json only; codex-args writes stdout).",
+    )
+    args = parser.parse_args(argv)
+
+    if args.format == "json":
+        if not args.key:
+            parser.error("--key is required when --format json")
+        if args.out is None:
+            parser.error("out is required when --format json")
+        merge_json(args.shared, args.template, args.out, args.key, args.merge_into_existing)
+    else:  # codex-args
+        if args.key:
+            parser.error("--key is not accepted when --format codex-args")
+        if args.merge_into_existing:
+            parser.error("--merge-into-existing is not accepted when --format codex-args")
+        if args.out is not None:
+            parser.error("out path is not accepted when --format codex-args (result goes to stdout)")
+        emit_codex_args(args.shared, args.template)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/.devenv/shared/claude-code.json b/.devenv/shared/claude-code.json
new file mode 100644
index 0000000000..9091361a06
--- /dev/null
+++ b/.devenv/shared/claude-code.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest", "--cdp-endpoint=http://127.0.0.1:9222"]
+    }
+  }
+}
diff --git a/.devenv/shared/codex.toml b/.devenv/shared/codex.toml
new file mode 100644
index 0000000000..1071c8ccf8
--- /dev/null
+++ b/.devenv/shared/codex.toml
@@ -0,0 +1,8 @@
+# Workspace-independent MCP servers for the OpenAI Codex CLI.
+# This block is concatenated with the port-substituted templates/codex.toml
+# by manage.sh's write-instance-mcp-configs to produce .codex/config.toml at
+# the workspace root.
+
+[mcp_servers.playwright]
+command = "npx"
+args = ["@playwright/mcp@latest", "--cdp-endpoint=http://127.0.0.1:9222"]
diff --git a/.devenv/shared/opencode.json b/.devenv/shared/opencode.json
new file mode 100644
index 0000000000..15d8f9372d
--- /dev/null
+++ b/.devenv/shared/opencode.json
@@ -0,0 +1,9 @@
+{
+  "mcp": {
+    "playwright": {
+      "type": "local",
+      "command": ["npx", "@playwright/mcp@latest", "--cdp-endpoint=http://127.0.0.1:9222"],
+      "enabled": true
+    }
+  }
+}
diff --git a/.devenv/shared/vscode.json b/.devenv/shared/vscode.json
new file mode 100644
index 0000000000..bb1a458d0f
--- /dev/null
+++ b/.devenv/shared/vscode.json
@@ -0,0 +1,9 @@
+{
+  "servers": {
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@playwright/mcp@latest", "--cdp-endpoint=http://127.0.0.1:9222"]
+    }
+  }
+}
diff --git a/.devenv/templates/claude-code.json b/.devenv/templates/claude-code.json
new file mode 100644
index 0000000000..192a61a177
--- /dev/null
+++ b/.devenv/templates/claude-code.json
@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "penpot": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "http://localhost:${PENPOT_MCP_PORT}/mcp", "--allow-http"]
+    },
+    "serena-devenv": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "http://localhost:${SERENA_MCP_PORT}/mcp", "--allow-http"]
+    }
+  }
+}
diff --git a/.devenv/templates/codex.toml b/.devenv/templates/codex.toml
new file mode 100644
index 0000000000..3ac341a7fa
--- /dev/null
+++ b/.devenv/templates/codex.toml
@@ -0,0 +1,10 @@
+# Workspace-specific MCP servers for the OpenAI Codex CLI. The PENPOT_MCP_PORT
+# and SERENA_MCP_PORT placeholders below are filled in per workspace by
+# manage.sh's write-instance-mcp-configs, then the result is concatenated
+# with shared/codex.toml to produce .codex/config.toml.
+
+[mcp_servers.penpot]
+url = "http://localhost:${PENPOT_MCP_PORT}/mcp"
+
+[mcp_servers.serena-devenv]
+url = "http://localhost:${SERENA_MCP_PORT}/mcp"
diff --git a/.devenv/templates/opencode.json b/.devenv/templates/opencode.json
new file mode 100644
index 0000000000..4d2db43297
--- /dev/null
+++ b/.devenv/templates/opencode.json
@@ -0,0 +1,14 @@
+{
+  "mcp": {
+    "penpot": {
+      "type": "remote",
+      "url": "http://localhost:${PENPOT_MCP_PORT}/mcp",
+      "enabled": true
+    },
+    "serena-devenv": {
+      "type": "remote",
+      "url": "http://localhost:${SERENA_MCP_PORT}/mcp",
+      "enabled": true
+    }
+  }
+}
diff --git a/.devenv/templates/vscode.json b/.devenv/templates/vscode.json
new file mode 100644
index 0000000000..843b5555b4
--- /dev/null
+++ b/.devenv/templates/vscode.json
@@ -0,0 +1,12 @@
+{
+  "servers": {
+    "penpot": {
+      "type": "http",
+      "url": "http://localhost:${PENPOT_MCP_PORT}/mcp"
+    },
+    "serena-devenv": {
+      "type": "http",
+      "url": "http://localhost:${SERENA_MCP_PORT}/mcp"
+    }
+  }
+}
diff --git a/.gitignore b/.gitignore
index ca6b947232..f800ad7f53 100644
--- a/.gitignore
+++ b/.gitignore
@@ -95,4 +95,7 @@
 /.idea
 /.claude
 /.playwright-mcp
+/.devenv/mcp/
+/opencode.json
+/.codex/
 /tools/__pycache__
diff --git a/.serena/memories/backend/core.md b/.serena/memories/backend/core.md
index 65f513e17c..b7a9199965 100644
--- a/.serena/memories/backend/core.md
+++ b/.serena/memories/backend/core.md
@@ -7,6 +7,7 @@ Backend: JVM Clojure; Integrant; PostgreSQL; Redis/Valkey; RPC; HTTP; storage; m
 - RPC, DB helpers, workers, cron: `mem:backend/rpc-db-worker-subtleties`
 - HTTP sessions, config, storage, media, file data persistence: `mem:backend/http-storage-filedata-subtleties`
 - Auth flows, permission model, teams, projects, invitations, comments, webhooks, audit: `mem:backend/auth-permissions-product-domains`
+- Services, task-queue/Pub-Sub topology constraints -> `mem:prod-infra/core`.
 
 ## Stable namespace map
 
diff --git a/.serena/memories/critical-info.md b/.serena/memories/critical-info.md
index 008b611b8b..17bb15bc55 100644
--- a/.serena/memories/critical-info.md
+++ b/.serena/memories/critical-info.md
@@ -13,15 +13,15 @@ You are working on the GitHub project `penpot/penpot`, a monorepo.
 - You have access to the GitHub CLI `gh` or corresponding MCP tools.
 - Issues are also managed on Taiga. Read issues using the `read_taiga_issue` tool.
 - Before writing code, analyze the task in depth and describe your plan. If the task is complex, break it down into atomic steps.
-* After making changes, run the applicable lint and format checks for the affected module before considering the work done (per example `mem:backend/core` or `mem:frontend/core`).
-
+  *After making changes, run the applicable lint and format checks for the affected module before considering the work done (per example `mem:backend/core` or `mem:frontend/core`).
+- Never run anything that destroys data without explicit permission, including `drop-devenv`, `docker compose down -v`, `docker volume rm ...`. The user's real work lives in the volumes of the shared infra.
 
 # Project modules
 
 This is a monorepo. Principles that apply to one module do *not* generally apply to others. Do not make assumptions.
 
 - `frontend/`: ClojureScript + SCSS SPA/design editor.
-- `backend/`: JVM Clojure HTTP/RPC server with PostgreSQL, Redis, storage, mail, and workers.
+- `backend/`: JVM Clojure HTTP/RPC server with PostgreSQL, Redis, storage, mail, and workers.Runtime services and the task-queue vs Pub/Sub topology that constrains horizontal scaling: `mem:prod-infra/core`.
 - `common/`: shared CLJC data types, geometry, schemas, file/change logic, and utilities.
 - `render-wasm/`: Rust -> WebAssembly Skia renderer consumed by frontend.
 - `exporter/`: ClojureScript/Node headless Playwright SVG/PDF export.
@@ -36,7 +36,9 @@ module. You can read it from `mem:<MODULE>/core`
 # Low-centrality project paths
 
 - `docker/` contains devenv related code, not needed unless specifically instructed.
-   More info in docs/technical-guide if instructed to work on this.
+   When working on devenv startup, compose layout, instance config (`defaults.env`),
+   tmux session lifecycle, MinIO provisioning, or anything in `manage.sh`'s
+   `*-devenv` commands, read `mem:devenv/core`.
 - `experiments/` contains standalone experimental HTML/JS/scripts; treat it as non-core unless the user explicitly asks about it.
 - `sample_media/` contains sample image/icon media and config used as fixtures/demo material; do not infer app behavior from it.
 
diff --git a/.serena/memories/devenv/core.md b/.serena/memories/devenv/core.md
new file mode 100644
index 0000000000..e612a5f923
--- /dev/null
+++ b/.serena/memories/devenv/core.md
@@ -0,0 +1,73 @@
+# Devenv startup and configuration
+
+Compose-based dev environment under `docker/devenv/`, driven by `manage.sh`. Parallel instances share infra + Postgres + MinIO; each instance has its own `main` container, Valkey, source checkout, tmux session.
+
+## Compose project layout
+
+- `penpotdev-infra`: shared `postgres`, `minio`, `minio-setup`, `mailer`, `ldap`. File: `docker-compose.infra.yml`.
+- `penpotdev-wsN` (N=0,1,…): per-instance `main` + `redis` (Valkey). File: `docker-compose.main.yml`. ws0 (a.k.a. `main`) binds `$PWD`; ws1+ bind clones at `${PENPOT_WORKSPACES_DIR}/wsN/` (default `~/.penpot/penpot_workspaces/`), maintained by the developer.
+- All projects join external network `penpot_shared`. Created idempotently by `ensure-devenv-network`, never removed by lifecycle commands.
+
+## Source-of-truth files
+
+- `docker/devenv/defaults.env`: ws0 baseline — container/volume names, runtime env, published host ports, tmux defaults. `manage.sh` aborts if unreadable.
+- For ws1+, `instance-env-overrides` computes the per-instance overrides (container/volume names, host ports offset `10000·N`, `PENPOT_PUBLIC_URI`, `PENPOT_REDIS_URI`, `PENPOT_BACKEND_WORKER=false`) and `instance-compose` injects them as env vars at compose time — never written to disk, recomputed each call so they can't drift. ws0 uses `defaults.env` as-is.
+- `backend/scripts/_env`: backend-internal only — secret keys, `PENPOT_FLAGS` (with `enable-backend-worker` gated on `PENPOT_BACKEND_WORKER`), `JAVA_OPTS`, `setup_minio()`. Never duplicates `defaults.env`.
+- Compose files use pure `${VAR}` substitution; missing var = compose fails.
+
+## Invariants
+
+- `infra-compose` / `instance-compose` wrap `docker compose` with `env -i`, then re-inject what compose needs. Stripping is required because `defaults.env` is sourced into manage.sh's shell at startup (stale values would leak); the ws1+ overrides are deliberately re-injected as shell env vars precisely because Compose gives shell precedence over `--env-file`, so they override the `defaults.env` baseline.
+- Volume names pinned via `name:` (PENPOT_*_VOLUME), decoupled from the compose project name. ws1+ inject distinct per-instance volume names; ws0 keeps the historical `penpotdev_*` physical names so project renames never require data migration.
+- Network aliases (`- main`, `- redis`) are not declared in main.yml. Compose's auto-service-alias still registers `redis` on the shared network, so DNS for `redis` is non-deterministic with multiple instances. Backend uses `PENPOT_REDIS_URI=redis://penpot-devenv-wsN-valkey/0` (container_name) instead.
+- No cross-project `depends_on`. `manage.sh ensure-infra-up` `docker wait`s on the `minio-setup` one-shot.
+- `JAVA_OPTS` in `manage.sh` is shadowed inside the container by `_env`. The `-e JAVA_OPTS=...` flag only matters for processes that don't source `_env`.
+
+## Worker policy
+
+Backend workers run only on ws0. `_env` gates `enable-backend-worker` on `PENPOT_BACKEND_WORKER`; ws1+ inject it as false. ws0 must be running whenever any ws1+ is running, and is the last instance to stop — `run-devenv-agentic --ws N` (N≥1) auto-starts ws0 first; `stop-devenv` refuses to stop ws0 while any ws1+ is up. Workers are pure fire-and-forget: `wrk/submit!` inserts a row into the shared Postgres `task` table and returns; RPC handlers never wait on completion and workers never publish to msgbus. The reason for "ws0 only" is avoiding multi-instance worker races (cron dedup is best-effort across instances, `wrk/submit!` `dedupe` is racy across submitters); details in `mem:prod-infra/core`.
+
+## Port layout
+
+Container-internal ports fixed; host side offset `10000·N`.
+
+| ws0 | ws1 | wsN | container | role |
+|---|---|---|---|---|
+| 3449 | 13449 | 3449+10000·N | 3449 | public HTTPS (Caddy; `/mcp/ws` same-origin) |
+| 3449/udp | 13449/udp | … | 3449/udp | HTTP/3 |
+| 4401 | 14401 | … | 4401 | MCP HTTP stream |
+| 4403 | 14403 | … | 4403 | MCP REPL |
+| 14181 | 24181 | … | 14281 | Serena MCP |
+| 14182 | 24182 | … | 24282 | Serena dashboard |
+
+Everything else (frontend dev, backend API, exporter, storybook, REPLs, plugin dev, MCP inspector/WebSocket) is in-process or same-origin via Caddy/nginx. Infra publishes: mailer 1080, ldap 10389/10636 (singletons, not offset).
+
+## Tmux + MCP routing
+
+`docker/devenv/files/start-tmux.sh` is session-level idempotent. Reads `PENPOT_TMUX_ATTACH`. If the session exists it attaches or exits; otherwise creates 4 base windows (frontend watch / storybook / exporter / backend) plus `mcp` (when `enable-mcp` in `PENPOT_FLAGS`) and `serena` (when `SERENA_ENABLED=true`). `run-devenv-agentic` always sets both env vars. The legacy `run-devenv` alias doesn't, hence its 4-window-only session. To switch from a legacy session to agentic, `stop-devenv` then `run-devenv-agentic` — the conditional windows are only added at session create time.
+
+MCP plugin routing is same-origin: frontend uses `<public-uri>/mcp/ws`, per-instance nginx proxies to MCP port 4401 in-container. For the plugin↔MCP server wiring (how the browser plugin discovers the URL, the in-memory connection registry, why DB-mediated routing isn't needed), see `mem:mcp/core`.
+
+## Workspace orchestration (ws1+)
+
+Workspace directories are user-maintained at `${PENPOT_WORKSPACES_DIR}/wsN`. `run-devenv-agentic --ws i` syncs only when `--sync` is passed, with one exception: if the workspace directory is missing on first use, sync runs implicitly to seed it.
+
+`sync-workspace wsN`:
+1. `assert-clean-git-state` — refuses on `.git/{rebase-apply,rebase-merge,MERGE_HEAD,CHERRY_PICK_HEAD,index.lock}`. No `--sync-force` escape.
+2. `rsync -a --delete $PWD/.git/ $workspace/.git/`.
+3. `git ls-files -z --cached --others --exclude-standard` → `rsync --files-from` (Git is the authority on tracked files; rsync's gitignore filter would drop committed files under gitignored parents like `.clj-kondo/config.edn`).
+4. Initial-only copy of `frontend/resources/public/js/config.js` (gitignored, but agentic mode needs it). After the first sync the workspace's copy belongs to the developer — subsequent syncs leave it alone.
+5. `git switch -C "wsN/<current-branch>"` inside the workspace.
+
+No `--delete` on the working-tree pass: gitignored caches in the workspace survive. Workspace dir + named volumes survive `compose down`.
+
+## CLI surface
+
+- `run-devenv-agentic [--ws main|0|wsN|N] [--sync] [--serena-context CTX]`: bring one instance up. Agentic only — MCP and Serena windows are always created. Default target main. Errors out if the target is already running. `--sync` is rejected on main; on ws1+ it's optional (forced only when the workspace dir does not exist yet). Auto-starts ws0 first when the target is ws1+ and ws0 is not yet up.
+- `stop-devenv [--ws main|0|wsN|N] [--all]`: stop instances. Flags mutually exclusive. `--ws N` (N≥1) stops just that workspace. `--ws 0` or no flag stops ws0 + shared infra, refused while any ws1+ is running. `--all` stops every ws highest-first then ws0, then infra.
+- `run-devenv`: legacy alias, ws0 non-agentic attached.
+- `attach-devenv [--ws main|0|wsN|N]`: pure attach. Fails fast if instance/session missing.
+- `run-devenv-shell [--instance 0|wsN|N] [cmd...]`: bash in target instance. (`--instance` flag not yet renamed to `--ws`.)
+- `start-devenv` / `log-devenv` / `drop-devenv`: legacy paths around ws0 + shared infra. `drop-devenv` never removes volumes.
+
+`exporter/scripts/run` and `wait-and-start.sh` source `backend/scripts/_env` then `_env.local` if present.
diff --git a/.serena/memories/mcp/core.md b/.serena/memories/mcp/core.md
index ba794b1d0f..772f7a3949 100644
--- a/.serena/memories/mcp/core.md
+++ b/.serena/memories/mcp/core.md
@@ -85,3 +85,11 @@ From the `mcp/` directory, run
 
 * `pnpm run build` to test the build of all packages
 * `pnpm run fmt` to apply the auto-formatter
+
+## Devenv plugin/server wiring
+
+In the normal Penpot devenv MCP path, the browser plugin does not discover or route through Postgres. The frontend provides the plugin extension API with `mcp.getServerUrl()`, currently derived from `frontend/src/app/config.cljs` as `penpotMcpServerURI` if set, otherwise `<public-uri>/mcp/ws`. The MCP plugin opens a direct WebSocket to that URL and appends the current MCP access token as a query parameter.
+
+The live plugin connection registry is in-memory inside each MCP server process (`PluginBridge.connectedClients` / `clientsByToken`). The database only stores MCP access tokens and profile props such as `mcp-enabled`; it does not manage which plugin is connected to which MCP server.
+
+For parallel devenvs, prefer same-origin MCP routing: each Penpot instance should expose `/mcp/ws` through its own nginx/Caddy path to the MCP server running inside the same main container. Keep container-internal ports fixed (MCP defaults `4401/4402/4403`, backend/exporter/frontend defaults, etc.) and only offset host-side published ports per instance. If internal ports are offset, hardcoded local proxy config such as `docker/devenv/files/nginx.conf` will misroute unless templated too.
diff --git a/.serena/memories/prod-infra/core.md b/.serena/memories/prod-infra/core.md
new file mode 100644
index 0000000000..e86eb69a32
--- /dev/null
+++ b/.serena/memories/prod-infra/core.md
@@ -0,0 +1,33 @@
+# Production infrastructure (services Penpot depends on)
+
+Backend (`app.config`, `PENPOT_*` env vars) is parameterized; deployments choose providers.
+
+## Services
+
+- **PostgreSQL**: durable store. Profiles, teams, files, sessions, audit, `storage_object` metadata, the `task` queue, `scheduled_task` cron registry, migrations. File-data also lives here when the file-data backend is `legacy-db`/`db`. One shared DB across all backends.
+- **Redis (Valkey-compatible)**: per-backend message bus and cache. Concrete uses: msgbus Pub/Sub for collaborative-editing broadcasts and team/profile-org notifications fired by RPC handlers (`app.rpc.notifications`, `files_update`, `teams`, `websocket`); file-summary cache gated by `enable-redis-cache`; rate-limit counters; and the dispatcher→runner work hand-off list `penpot.worker.queue:<tenant>:<queue>`. `PENPOT_REDIS_URI`.
+- **Object storage**: backends `:s3` and `:fs`. S3 in prod; devenv uses MinIO. Holds uploaded media, file-data when the file-data backend is `storage`, exports. Backend-side details (resolve, dedup, bucket set, file-data backends): `mem:backend/http-storage-filedata-subtleties`.
+- **SMTP mailer**: invitations, password resets, email verification (sent via the `:sendmail` worker task).
+- **LDAP** (optional auth provider): helpers in `app.auth.*`, gated by `enable-login-with-ldap`.
+
+## Task queue and worker model
+
+Async tasks are enqueued via `wrk/submit!` (`app.worker`), which inserts a row into the shared Postgres `task` table tagged with `queue = "<tenant>:<queue-name>"`. Submission is **fire-and-forget** — RPC handlers never poll, never wait, and workers never publish to msgbus. The only completion signal is the `task` row's `status` / `completed_at` columns, which nothing in `rpc/` reads. Soft-delete RPCs return immediately after marking the top-level row, leaving the cascade and reaping to workers.
+
+Workers run on backends with `enable-backend-worker` in `PENPOT_FLAGS`. Each worker-enabled backend has a `dispatcher` (polls `task` with `FOR UPDATE SKIP LOCKED`, marks status='scheduled', RPUSHes claimed task IDs into **its own** Redis list) and one or more `runner`s per queue (BLPOP from that same local list, execute, update the Postgres row). The Redis hand-off list is purely intra-backend — cross-backend coordination happens at the Postgres row level.
+
+## Cross-backend safety
+
+Postgres row locking is the only correctness primitive: `task` claims via `FOR UPDATE SKIP LOCKED`, cron firing via `FOR UPDATE SKIP LOCKED` on the `scheduled_task` row, plus task-handler-internal locks (e.g. `file_gc_scheduler` locks candidate file rows). This makes the work-claim path safe across any number of worker-enabled backends.
+
+Two known race patterns survive multi-backend operation:
+
+- **Cron dedup is best-effort.** The lock on `scheduled_task` is released when the task body finishes. If two backends' cron timers fire for the same scheduled instant with a gap larger than the task body's runtime, both execute it. Penpot's cron entries are idempotent (`session-gc`, `objects-gc`, `storage-gc-*`, `tasks-gc`, `upload-session-gc`, `file-gc-scheduler`); the exceptions are `:telemetry` (would double-report) and `:audit-log-archive` (depends on archive target idempotency).
+- **`wrk/submit! ::dedupe true`** does a non-atomic `DELETE` then `INSERT`. Concurrent cross-backend submits can both bypass the `DELETE` (each sees the other's uncommitted insert as absent) and end up with duplicate `'new'` rows. Each row claims and runs once independently, so the underlying work is fine; the "at most one pending" guarantee weakens.
+
+Penpot in production lives with both: horizontal-scale deployments accept "exactly-once" as "essentially-once for idempotent operations." Devenv parallel instances handle it by running workers only on ws0 (see `mem:devenv/core`).
+
+## See also
+
+- Devenv composition and the ws0-only worker placement: `mem:devenv/core`.
+- Storage backend resolution, dedup, file-data lifecycle: `mem:backend/http-storage-filedata-subtleties`.
diff --git a/backend/scripts/_env b/backend/scripts/_env
index 2a89244a81..b68d7d85ec 100644
--- a/backend/scripts/_env
+++ b/backend/scripts/_env
@@ -8,8 +8,18 @@ export PENPOT_SECRET_KEY=super-secret-devenv-key
 # DEPRECATED: only used for subscriptions
 export PENPOT_MANAGEMENT_API_KEY=super-secret-management-api-key
 
-export PENPOT_HOST=devenv
-export PENPOT_PUBLIC_URI=https://localhost:3449
+# Runtime config that varies per devenv instance (PENPOT_HOST, PENPOT_PUBLIC_URI,
+# PENPOT_DATABASE_*, PENPOT_REDIS_URI, PENPOT_OBJECTS_STORAGE_*, AWS_*) is owned by
+# docker/devenv/defaults.env and injected via the main service's env block.
+
+# Background worker flag is per-instance. Defaults to enabled (ws0); ws1+
+# overlays set PENPOT_BACKEND_WORKER=false so scheduled and async tasks only
+# run on ws0, keeping notification Pub/Sub bound to a single Valkey. See
+# mem:devenv/core for the rationale.
+__worker_flag=""
+if [[ "${PENPOT_BACKEND_WORKER:-true}" == "true" ]]; then
+    __worker_flag="enable-backend-worker"
+fi
 
 export PENPOT_FLAGS="\
        $PENPOT_FLAGS \
@@ -20,7 +30,7 @@ export PENPOT_FLAGS="\
        disable-login-with-github \
        disable-login-with-gitlab \
        disable-telemetry \
-       enable-backend-worker \
+       $__worker_flag \
        enable-backend-asserts \
        disable-feature-fdata-pointer-map \
        enable-feature-fdata-objects-map \
@@ -60,12 +70,6 @@ export PENPOT_HTTP_SERVER_MAX_MULTIPART_BODY_SIZE=314572800
 
 export PENPOT_USER_FEEDBACK_DESTINATION="support@example.com"
 
-export AWS_ACCESS_KEY_ID=penpot-devenv
-export AWS_SECRET_ACCESS_KEY=penpot-devenv
-export PENPOT_OBJECTS_STORAGE_BACKEND=s3
-export PENPOT_OBJECTS_STORAGE_S3_ENDPOINT=http://minio:9000
-export PENPOT_OBJECTS_STORAGE_S3_BUCKET=penpot
-
 export PENPOT_NITRATE_BACKEND_URI=http://localhost:3000/admin-console
 
 export JAVA_OPTS="\
@@ -84,14 +88,14 @@ export JAVA_OPTS="\
        --enable-native-access=ALL-UNNAMED";
 
 function setup_minio() {
-    # Initialize MINIO config
-    mc alias set penpot-s3/ http://minio:9000 minioadmin minioadmin -q
-    mc admin user add penpot-s3 penpot-devenv penpot-devenv -q
-    mc admin user info penpot-s3 penpot-devenv |grep -F -q "readwrite"
-    if [ "$?" = "1" ]; then
-        mc admin policy attach penpot-s3 readwrite --user=penpot-devenv -q
+    if [ "${PENPOT_OBJECTS_STORAGE_BACKEND}" != "s3" ]; then
+        return 0
     fi
-    mc mb penpot-s3/penpot -p -q
+
+    # Shared MinIO user/policy provisioning is handled by docker-compose.infra.yml.
+    # Per process startup only ensures that the configured bucket exists.
+    mc alias set penpot-s3/ "${PENPOT_OBJECTS_STORAGE_S3_ENDPOINT}" minioadmin minioadmin -q
+    mc mb "penpot-s3/${PENPOT_OBJECTS_STORAGE_S3_BUCKET}" -p -q
 }
 
 
diff --git a/docker/devenv/defaults.env b/docker/devenv/defaults.env
new file mode 100644
index 0000000000..70368b3c64
--- /dev/null
+++ b/docker/devenv/defaults.env
@@ -0,0 +1,69 @@
+# Single source of truth for instance-specific devenv configuration.
+# Loaded by docker compose via --env-file and also sourced by manage.sh
+# (see manage.sh). This is the ws0 baseline; for ws1+ manage.sh injects the
+# per-instance values as environment variables (see instance-env-overrides),
+# which override these via Compose's shell-over-env-file precedence. Variables
+# not overridden fall back to the values here.
+#
+# Backend runtime defaults that compose does not care about live in
+# backend/scripts/_env.
+
+# Container names and volume names. Volumes are pinned by explicit name
+# (rather than relying on COMPOSE_PROJECT_NAME prefixing) so the physical
+# volumes survive project renames without a data migration. ws0 reuses the
+# pre-Stage-2 physical volume names (penpotdev_*).
+PENPOT_MAIN_CONTAINER_NAME=penpot-devenv-ws0-main
+PENPOT_VALKEY_CONTAINER_NAME=penpot-devenv-ws0-valkey
+PENPOT_VALKEY_HOSTNAME=penpot-devenv-ws0-valkey
+PENPOT_POSTGRES_DATA_VOLUME=penpotdev_postgres_data_pg16
+PENPOT_MINIO_DATA_VOLUME=penpotdev_minio_data
+PENPOT_USER_DATA_VOLUME=penpotdev_user_data
+PENPOT_VALKEY_DATA_VOLUME=penpotdev_valkey_data
+
+# Backend runtime config (passed to the container env block). PENPOT_REDIS_URI
+# is set explicitly per instance to match the per-instance Valkey container
+# name; ws1+ overlays override this.
+PENPOT_HOST=devenv
+PENPOT_PUBLIC_URI=https://localhost:3449
+PENPOT_DATABASE_URI=postgresql://postgres/penpot
+PENPOT_DATABASE_USERNAME=penpot
+PENPOT_DATABASE_PASSWORD=penpot
+PENPOT_DATABASE_MAX_POOL_SIZE=20
+PENPOT_REDIS_URI=redis://penpot-devenv-ws0-valkey/0
+
+# Object storage (MinIO user/policy are provisioned by the infra compose file).
+PENPOT_OBJECTS_STORAGE_BACKEND=s3
+PENPOT_OBJECTS_STORAGE_S3_ENDPOINT=http://minio:9000
+PENPOT_OBJECTS_STORAGE_S3_BUCKET=penpot
+AWS_ACCESS_KEY_ID=penpot-devenv
+AWS_SECRET_ACCESS_KEY=penpot-devenv
+
+# Published host ports. Only ports that need to be reachable from outside the
+# container are exposed; everything else (frontend dev server, backend API,
+# storybook, exporter, REPLs, plugins, MCP inspector/websocket, aux) is
+# accessed in-process or through the same-origin Caddy/nginx proxy at
+# PENPOT_PUBLIC_HTTP_PORT. Container-internal ports remain fixed; per-instance
+# overlays may offset these host-side values.
+PENPOT_PUBLIC_HTTP_PORT=3449
+PENPOT_MCP_SERVER_PORT=4401
+PENPOT_MCP_REPL_PORT=4403
+
+SHADOW_SERVER_URL=wss://localhost:3449
+
+# Serena (agentic devenv). These are the published host ports for ws0; ws1+
+# offset them by 10000*N. The container-internal ports (Serena MCP 14281,
+# dashboard 24282) are fixed by Serena and mapped to these in compose.
+SERENA_EXTERNAL_PORT=14181
+SERENA_DASHBOARD_EXTERNAL_PORT=14182
+
+# Backend worker (scheduled + async tasks). ws0 only; per-instance overlays
+# for ws1+ override this to false. See mem:devenv/core.
+PENPOT_BACKEND_WORKER=true
+
+# Tmux session inside the main container.
+PENPOT_TMUX_ATTACH=true
+
+# Base directory holding non-main workspace clones (one subdir per wsN, N>=1).
+# Consumed by manage.sh only. Default lives in manage.sh ($HOME expansion is
+# not applied to values in this file). Export PENPOT_WORKSPACES_DIR to
+# override.
diff --git a/docker/devenv/docker-compose.infra.yml b/docker/devenv/docker-compose.infra.yml
new file mode 100644
index 0000000000..5bf979c4f8
--- /dev/null
+++ b/docker/devenv/docker-compose.infra.yml
@@ -0,0 +1,99 @@
+networks:
+  default:
+    name: penpot_shared
+    external: true
+
+volumes:
+  postgres_data_pg16:
+    name: ${PENPOT_POSTGRES_DATA_VOLUME}
+  minio_data:
+    name: ${PENPOT_MINIO_DATA_VOLUME}
+
+services:
+  minio:
+    image: "minio/minio:RELEASE.2025-04-03T14-56-28Z"
+    command: minio server /mnt/data --console-address ":9001"
+
+    volumes:
+      - "minio_data:/mnt/data"
+
+    environment:
+      - MINIO_ROOT_USER=minioadmin
+      - MINIO_ROOT_PASSWORD=minioadmin
+
+    networks:
+      default:
+        aliases:
+          - minio
+
+  minio-setup:
+    image: "minio/mc:latest"
+    depends_on:
+      - minio
+    entrypoint: ["/bin/sh", "-c"]
+    command:
+      - |
+        attempts=0
+        until mc alias set penpot-s3 http://minio:9000 minioadmin minioadmin -q; do
+          attempts=$$((attempts + 1))
+          if [ "$$attempts" -ge 30 ]; then
+            echo "minio-setup: gave up waiting for MinIO after $$attempts attempts" >&2
+            exit 1
+          fi
+          sleep 1
+        done
+        mc admin user info penpot-s3 penpot-devenv >/dev/null 2>&1 || mc admin user add penpot-s3 penpot-devenv penpot-devenv -q
+        mc admin policy attach penpot-s3 readwrite --user=penpot-devenv -q
+    networks:
+      default:
+
+  postgres:
+    image: postgres:16.8
+    command: postgres -c config_file=/etc/postgresql.conf
+    restart: always
+    stop_signal: SIGINT
+    environment:
+      - POSTGRES_INITDB_ARGS=--data-checksums
+      - POSTGRES_DB=penpot
+      - POSTGRES_USER=penpot
+      - POSTGRES_PASSWORD=penpot
+    volumes:
+      - ./files/postgresql.conf:/etc/postgresql.conf:z
+      - ./files/postgresql_init.sql:/docker-entrypoint-initdb.d/init.sql:z
+      - postgres_data_pg16:/var/lib/postgresql/data
+    networks:
+      default:
+        aliases:
+          - postgres
+
+  mailer:
+    image: sj26/mailcatcher:latest
+    restart: always
+    expose:
+      - '1025'
+    ports:
+      - "1080:1080"
+
+    networks:
+      default:
+        aliases:
+          - mailer
+
+  # https://github.com/rroemhild/docker-test-openldap
+  ldap:
+    image: rroemhild/test-openldap:2.1
+    expose:
+      - '10389'
+      - '10636'
+    ports:
+      - "10389:10389"
+      - "10636:10636"
+    ulimits:
+      nofile:
+        soft: 1024
+        hard: 1024
+
+    networks:
+      default:
+        aliases:
+          - ldap
diff --git a/docker/devenv/docker-compose.main.yml b/docker/devenv/docker-compose.main.yml
new file mode 100644
index 0000000000..fb8caf78c7
--- /dev/null
+++ b/docker/devenv/docker-compose.main.yml
@@ -0,0 +1,106 @@
+networks:
+  default:
+    name: penpot_shared
+    external: true
+
+volumes:
+  user_data:
+    name: ${PENPOT_USER_DATA_VOLUME}
+  valkey_data:
+    name: ${PENPOT_VALKEY_DATA_VOLUME}
+
+services:
+  main:
+    privileged: true
+    image: "penpotapp/devenv:latest"
+    build:
+      context: "."
+    container_name: "${PENPOT_MAIN_CONTAINER_NAME}"
+    stop_signal: SIGINT
+
+    # postgres / minio / minio-setup live in the penpotdev-infra compose
+    # project and cannot be referenced via depends_on across projects.
+    # manage.sh waits for infra readiness before bringing main up.
+    depends_on:
+      redis:
+        condition: service_started
+
+    volumes:
+      - "user_data:/home/penpot/"
+      - "${PENPOT_SOURCE_PATH}:/home/penpot/penpot:z"
+
+    ports:
+      # Host ports are instance-specific; container ports stay fixed.
+      - ${PENPOT_PUBLIC_HTTP_PORT}:3449
+      - ${PENPOT_PUBLIC_HTTP_PORT}:3449/udp
+
+      # MCP
+      - ${PENPOT_MCP_SERVER_PORT}:4401
+      - ${PENPOT_MCP_REPL_PORT}:4403
+
+      # Serena MCP server (agentic mode only). Internal ports fixed by Serena.
+      - ${SERENA_EXTERNAL_PORT}:14281
+      - ${SERENA_DASHBOARD_EXTERNAL_PORT}:24282
+
+    environment:
+      - EXTERNAL_UID=${CURRENT_USER_ID}
+
+      # SMTP setup (shared infra service; identical across instances)
+      - PENPOT_SMTP_ENABLED=true
+      - PENPOT_SMTP_DEFAULT_FROM=no-reply@example.com
+      - PENPOT_SMTP_DEFAULT_REPLY_TO=no-reply@example.com
+      - PENPOT_SMTP_HOST=mailer
+      - PENPOT_SMTP_PORT=1025
+      - PENPOT_SMTP_USERNAME=
+      - PENPOT_SMTP_PASSWORD=
+      - PENPOT_SMTP_SSL=false
+      - PENPOT_SMTP_TLS=false
+
+      # LDAP setup (shared infra service; identical across instances)
+      - PENPOT_LDAP_HOST=ldap
+      - PENPOT_LDAP_PORT=10389
+      - PENPOT_LDAP_SSL=false
+      - PENPOT_LDAP_STARTTLS=false
+      - PENPOT_LDAP_BASE_DN=ou=people,dc=planetexpress,dc=com
+      - PENPOT_LDAP_BIND_DN=cn=admin,dc=planetexpress,dc=com
+      - PENPOT_LDAP_BIND_PASSWORD=GoodNewsEveryone
+      - PENPOT_LDAP_ATTRS_USERNAME=uid
+      - PENPOT_LDAP_ATTRS_EMAIL=mail
+      - PENPOT_LDAP_ATTRS_FULLNAME=cn
+      - PENPOT_LDAP_ATTRS_PHOTO=jpegPhoto
+
+      # Per-instance runtime config. Defaults live in defaults.env.
+      - PENPOT_HOST=${PENPOT_HOST}
+      - PENPOT_PUBLIC_URI=${PENPOT_PUBLIC_URI}
+      - PENPOT_DATABASE_URI=${PENPOT_DATABASE_URI}
+      - PENPOT_DATABASE_USERNAME=${PENPOT_DATABASE_USERNAME}
+      - PENPOT_DATABASE_PASSWORD=${PENPOT_DATABASE_PASSWORD}
+      - PENPOT_DATABASE_MAX_POOL_SIZE=${PENPOT_DATABASE_MAX_POOL_SIZE}
+      - PENPOT_REDIS_URI=${PENPOT_REDIS_URI}
+      - PENPOT_OBJECTS_STORAGE_BACKEND=${PENPOT_OBJECTS_STORAGE_BACKEND}
+      - PENPOT_OBJECTS_STORAGE_S3_ENDPOINT=${PENPOT_OBJECTS_STORAGE_S3_ENDPOINT}
+      - PENPOT_OBJECTS_STORAGE_S3_BUCKET=${PENPOT_OBJECTS_STORAGE_S3_BUCKET}
+      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
+      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
+      - PENPOT_BACKEND_WORKER=${PENPOT_BACKEND_WORKER}
+      - PENPOT_TMUX_ATTACH=${PENPOT_TMUX_ATTACH}
+
+      # Agentic devenv: set to a commit/tag to update Serena on startup,
+      # leave empty to skip update and use the version baked into the image.
+      - SERENA_UPDATE_VERSION=1.5.0
+      - SHADOW_SERVER_URL=${SHADOW_SERVER_URL}
+
+    networks:
+      - default
+
+  redis:
+    image: valkey/valkey:8.1
+    hostname: "${PENPOT_VALKEY_HOSTNAME}"
+    container_name: "${PENPOT_VALKEY_CONTAINER_NAME}"
+    restart: always
+    command: valkey-server --save 120 1 --loglevel warning
+    volumes:
+      - "valkey_data:/data"
+
+    networks:
+      - default
diff --git a/docker/devenv/docker-compose.yaml b/docker/devenv/docker-compose.yaml
deleted file mode 100644
index 6963b18d8a..0000000000
--- a/docker/devenv/docker-compose.yaml
+++ /dev/null
@@ -1,180 +0,0 @@
-networks:
-  default:
-    driver: bridge
-    ipam:
-      config:
-        - subnet: 172.177.9.0/24
-
-volumes:
-  postgres_data_pg16:
-  user_data:
-  minio_data:
-  valkey_data:
-
-services:
-  main:
-    privileged: true
-    image: "penpotapp/devenv:latest"
-    build:
-      context: "."
-    container_name: "penpot-devenv-main"
-    stop_signal: SIGINT
-
-    depends_on:
-      - postgres
-      - redis
-      # - keycloak
-
-    volumes:
-      - "user_data:/home/penpot/"
-      - "${PWD}:/home/penpot/penpot:z"
-
-    ports:
-      - 3447:3447
-      - 3448:3448
-      - 3449:3449
-      - 3449:3449/udp
-      - 3450:3450
-      - 6006:6006
-      - 6060:6060
-      - 6061:6061
-      - 6062:6062
-      - 6063:6063
-      - 6064:6064
-      - 9000:9000
-      - 9001:9001
-      - 9090:9090
-      - 9091:9091
-
-      # MCP
-      - 4400:4400
-      - 4401:4401
-      - 4402:4402
-      - 4403:4403
-
-      # Plugins
-      - 4200:4200
-      - 4201:4201
-      - 4202:4202
-
-      # Serena MCP server (agentic mode only)
-      - ${SERENA_EXTERNAL_PORT:-14281}:14281
-      - ${SERENA_DASHBOARD_EXTERNAL_PORT:-14282}:24282
-
-    environment:
-      - EXTERNAL_UID=${CURRENT_USER_ID}
-      # SMTP setup
-      - PENPOT_SMTP_ENABLED=true
-      - PENPOT_SMTP_DEFAULT_FROM=no-reply@example.com
-      - PENPOT_SMTP_DEFAULT_REPLY_TO=no-reply@example.com
-      - PENPOT_SMTP_HOST=mailer
-      - PENPOT_SMTP_PORT=1025
-      - PENPOT_SMTP_USERNAME=
-      - PENPOT_SMTP_PASSWORD=
-      - PENPOT_SMTP_SSL=false
-      - PENPOT_SMTP_TLS=false
-
-      # LDAP setup
-      - PENPOT_LDAP_HOST=ldap
-      - PENPOT_LDAP_PORT=10389
-      - PENPOT_LDAP_SSL=false
-      - PENPOT_LDAP_STARTTLS=false
-      - PENPOT_LDAP_BASE_DN=ou=people,dc=planetexpress,dc=com
-      - PENPOT_LDAP_BIND_DN=cn=admin,dc=planetexpress,dc=com
-      - PENPOT_LDAP_BIND_PASSWORD=GoodNewsEveryone
-      - PENPOT_LDAP_ATTRS_USERNAME=uid
-      - PENPOT_LDAP_ATTRS_EMAIL=mail
-      - PENPOT_LDAP_ATTRS_FULLNAME=cn
-      - PENPOT_LDAP_ATTRS_PHOTO=jpegPhoto
-
-      # agentic devenv
-      # Serena update: set to a commit/tag to update Serena on startup, leave empty to skip update and use the version in the image
-      - SERENA_UPDATE_VERSION=1.5.0
-
-    networks:
-      default:
-        aliases:
-          - main
-
-  minio:
-    image: "minio/minio:RELEASE.2025-04-03T14-56-28Z"
-    command: minio server /mnt/data --console-address ":9001"
-
-    volumes:
-      - "minio_data:/mnt/data"
-
-    environment:
-      - MINIO_ROOT_USER=minioadmin
-      - MINIO_ROOT_PASSWORD=minioadmin
-
-    networks:
-      default:
-        aliases:
-          - minio
-
-  postgres:
-    image: postgres:16.8
-    command: postgres -c config_file=/etc/postgresql.conf
-    restart: always
-    stop_signal: SIGINT
-    environment:
-      - POSTGRES_INITDB_ARGS=--data-checksums
-      - POSTGRES_DB=penpot
-      - POSTGRES_USER=penpot
-      - POSTGRES_PASSWORD=penpot
-    volumes:
-      - ./files/postgresql.conf:/etc/postgresql.conf:z
-      - ./files/postgresql_init.sql:/docker-entrypoint-initdb.d/init.sql:z
-      - postgres_data_pg16:/var/lib/postgresql/data
-    networks:
-      default:
-        aliases:
-          - postgres
-
-  redis:
-    image: valkey/valkey:8.1
-    hostname: "penpot-devenv-valkey"
-    container_name: "penpot-devenv-valkey"
-    restart: always
-    command: valkey-server --save 120 1 --loglevel warning
-    volumes:
-      - "valkey_data:/data"
-
-    networks:
-      default:
-        aliases:
-          - redis
-
-  mailer:
-    image: sj26/mailcatcher:latest
-    restart: always
-    expose:
-      - '1025'
-    ports:
-      - "1080:1080"
-
-    networks:
-      default:
-        aliases:
-          - mailer
-
-
-  # https://github.com/rroemhild/docker-test-openldap
-  ldap:
-    image: rroemhild/test-openldap:2.1
-    expose:
-      - '10389'
-      - '10636'
-    ports:
-      - "10389:10389"
-      - "10636:10636"
-    ulimits:
-      nofile:
-        soft: 1024
-        hard: 1024
-
-    networks:
-      default:
-        aliases:
-          - ldap
-
diff --git a/docker/devenv/files/Caddyfile b/docker/devenv/files/Caddyfile
index a4e81434b0..1aa1f6b6a6 100644
--- a/docker/devenv/files/Caddyfile
+++ b/docker/devenv/files/Caddyfile
@@ -15,7 +15,3 @@ localhost:3449 {
 	# }
 	reverse_proxy localhost:4449
 }
-
-http://penpot-devenv-main:3450 {
-	reverse_proxy localhost:4449
-}
diff --git a/docker/devenv/files/nginx.conf b/docker/devenv/files/nginx.conf
index 5847e6551a..ce5566079f 100644
--- a/docker/devenv/files/nginx.conf
+++ b/docker/devenv/files/nginx.conf
@@ -136,6 +136,13 @@ http {
             proxy_http_version 1.1;
         }
 
+        location /api/remote-relay {
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection 'upgrade';
+            proxy_pass http://127.0.0.1:3448;
+            proxy_http_version 1.1;
+        }
+
         location /mcp/ws {
             proxy_set_header Upgrade $http_upgrade;
             proxy_set_header Connection 'upgrade';
diff --git a/docker/devenv/files/start-tmux.sh b/docker/devenv/files/start-tmux.sh
index ae61f32c5c..a029dbe84a 100755
--- a/docker/devenv/files/start-tmux.sh
+++ b/docker/devenv/files/start-tmux.sh
@@ -6,6 +6,23 @@ cd ~;
 
 source ~/.bashrc
 
+PENPOT_TMUX_SESSION="penpot"
+PENPOT_TMUX_ATTACH="${PENPOT_TMUX_ATTACH:-true}"
+
+function attach_or_exit() {
+    if [ "$PENPOT_TMUX_ATTACH" = "true" ]; then
+        exec tmux -2 attach-session -t "$PENPOT_TMUX_SESSION"
+    fi
+
+    echo "[start-tmux.sh] tmux session '$PENPOT_TMUX_SESSION' is running detached"
+    exit 0
+}
+
+if tmux has-session -t "$PENPOT_TMUX_SESSION" 2>/dev/null; then
+    echo "[start-tmux.sh] Reusing existing tmux session '$PENPOT_TMUX_SESSION'"
+    attach_or_exit
+fi
+
 echo "[start-tmux.sh] Installing node dependencies"
 pushd ~/penpot/frontend/
 ./scripts/setup;
@@ -14,32 +31,32 @@ pushd ~/penpot/exporter/
 ./scripts/setup;
 popd
 
-tmux -2 new-session -d -s penpot
+tmux -2 new-session -d -s "$PENPOT_TMUX_SESSION"
 
-tmux rename-window -t penpot:0 'frontend watch'
-tmux select-window -t penpot:0
-tmux send-keys -t penpot 'cd penpot/frontend' enter C-l
-tmux send-keys -t penpot './scripts/watch app' enter
+tmux rename-window -t "$PENPOT_TMUX_SESSION:0" 'frontend watch'
+tmux select-window -t "$PENPOT_TMUX_SESSION:0"
+tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/frontend' enter C-l
+tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/watch app' enter
 
-tmux new-window -t penpot:1 -n 'frontend storybook'
-tmux select-window -t penpot:1
-tmux send-keys -t penpot 'cd penpot/frontend' enter C-l
-tmux send-keys -t penpot './scripts/watch storybook' enter
+tmux new-window -t "$PENPOT_TMUX_SESSION:1" -n 'frontend storybook'
+tmux select-window -t "$PENPOT_TMUX_SESSION:1"
+tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/frontend' enter C-l
+tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/watch storybook' enter
 
-tmux new-window -t penpot:2 -n 'exporter'
-tmux select-window -t penpot:2
-tmux send-keys -t penpot 'cd penpot/exporter' enter C-l
-tmux send-keys -t penpot 'rm -f target/app.js*' enter C-l
-tmux send-keys -t penpot './scripts/watch' enter
+tmux new-window -t "$PENPOT_TMUX_SESSION:2" -n 'exporter'
+tmux select-window -t "$PENPOT_TMUX_SESSION:2"
+tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/exporter' enter C-l
+tmux send-keys -t "$PENPOT_TMUX_SESSION" 'rm -f target/app.js*' enter C-l
+tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/watch' enter
 
-tmux split-window -v
-tmux send-keys -t penpot 'cd penpot/exporter' enter C-l
-tmux send-keys -t penpot './scripts/wait-and-start.sh' enter
+tmux split-window -v -t "$PENPOT_TMUX_SESSION"
+tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/exporter' enter C-l
+tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/wait-and-start.sh' enter
 
-tmux new-window -t penpot:3 -n 'backend'
-tmux select-window -t penpot:3
-tmux send-keys -t penpot 'cd penpot/backend' enter C-l
-tmux send-keys -t penpot './scripts/start-dev' enter
+tmux new-window -t "$PENPOT_TMUX_SESSION:3" -n 'backend'
+tmux select-window -t "$PENPOT_TMUX_SESSION:3"
+tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/backend' enter C-l
+tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/start-dev' enter
 
 if echo "$PENPOT_FLAGS" | grep -q "enable-mcp"; then
     pushd ~/penpot/mcp/
@@ -47,10 +64,10 @@ if echo "$PENPOT_FLAGS" | grep -q "enable-mcp"; then
     pnpm run build;
     popd
 
-    tmux new-window -t penpot:4 -n 'mcp'
-    tmux select-window -t penpot:4
-    tmux send-keys -t penpot 'cd penpot/mcp' enter C-l
-    tmux send-keys -t penpot './scripts/start-mcp-devenv' enter
+    tmux new-window -t "$PENPOT_TMUX_SESSION:4" -n 'mcp'
+    tmux select-window -t "$PENPOT_TMUX_SESSION:4"
+    tmux send-keys -t "$PENPOT_TMUX_SESSION" 'cd penpot/mcp' enter C-l
+    tmux send-keys -t "$PENPOT_TMUX_SESSION" './scripts/start-mcp-devenv' enter
 fi
 
 if [ "${SERENA_ENABLED:-false}" = "true" ]; then
@@ -58,9 +75,9 @@ if [ "${SERENA_ENABLED:-false}" = "true" ]; then
         # update Serena (use sudo since the initial Serena installation is global; see Dockerfile)
         sudo -E uv tool install -p 3.13 serena-agent@${SERENA_UPDATE_VERSION} --prerelease=allow
     fi
-    tmux new-window -t penpot:5 -n 'serena'
-    tmux select-window -t penpot:5
-    tmux send-keys -t penpot "serena start-mcp-server --transport streamable-http --port 14281 --project penpot --context ${SERENA_CONTEXT} --host 0.0.0.0" enter
+    tmux new-window -t "$PENPOT_TMUX_SESSION:5" -n 'serena'
+    tmux select-window -t "$PENPOT_TMUX_SESSION:5"
+    tmux send-keys -t "$PENPOT_TMUX_SESSION" "serena start-mcp-server --transport streamable-http --port 14281 --project penpot --context ${SERENA_CONTEXT} --host 0.0.0.0" enter
 fi
 
-tmux -2 attach-session -t penpot
+attach_or_exit
diff --git a/docs/technical-guide/developer/agentic-devenv.md b/docs/technical-guide/developer/agentic-devenv.md
index 19940ccc00..ed362ce385 100644
--- a/docs/technical-guide/developer/agentic-devenv.md
+++ b/docs/technical-guide/developer/agentic-devenv.md
@@ -5,18 +5,73 @@ desc: Dive into agentic Penpot development.
 
 # Agentic Development Environment
 
-The agentic DevEnv is an extension of the standard DevEnv
-(the [general DevEnv instructions](/technical-guide/developer/devenv/) apply),
-which is optimised for AI agent-based development,
-adding additional tools and processes that support agentic automation.
+The agentic DevEnv is an extension of the standard DevEnv (the
+[general DevEnv instructions](/technical-guide/developer/devenv/) apply),
+optimised for AI agent-based development. It adds MCP servers (Penpot,
+Serena, Playwright) and supports a launcher that wires them into your AI client.
 
-The general workflow is as follows:
+Two things to know up front:
 
-1. Start the agentic DevEnv.
-2. Start a debugging-enabled browser and open Penpot, using a Penpot user with
-   the remote MCP integration enabled.
-3. Use an AI client (MCP client) which is connected to a suite of MCP servers
-   to solve development tasks.
+- **Parallel workspaces are first-class.** Run several devenv instances side
+  by side - one per AI agent if you like - each with its own source-tree
+  clone, ports, and tmux session. Pass `--ws N` to target one.
+- **Your existing AI-client config is preserved.** The launcher loads a
+  per-workspace MCP config on top of your global one.
+
+## Quick Start
+
+1. **Bring up one or more workspaces**[^cfg]:
+
+   ```bash
+   ./manage.sh run-devenv-agentic              # ws0 (the live repo)
+   ./manage.sh run-devenv-agentic --ws 1       # ws1 (sibling clone)
+   ```
+
+   Add `--ws 2`, `--ws 3`, … for more parallel workspaces.
+
+2. **Launch a browser with remote debugging enabled:**
+
+   For example, with Chrome:
+
+   ```bash
+   google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-debug-profile"
+   ```
+
+3. **Open Penpot in that browser:**
+
+   - ws0: <https://localhost:3449>
+   - ws1: <https://localhost:13449>
+   - etc. (ports are offset by `10000 × N` for `wsN`)
+
+   On first login per account, open settings → Integrations and toggle
+   "MCP Server" on. The agentic DevEnv runs the MCP server in single-user
+   mode - the key and proxied URL shown in the UI are not needed.
+
+4. **Launch your AI client** against the workspace you want it to drive:
+
+   ```bash
+   ./manage.sh start-coding-agent claude              # ws0
+   ./manage.sh start-coding-agent claude --ws 1       # ws1
+   ```
+
+   Supported clients: `claude` | `opencode` | `vscode` | `codex`.
+5. **Attach to the tmux session** for the workspace (optional):
+
+   ```bash
+   ./manage.sh attach-devenv            # ws0
+   ./manage.sh attach-devenv --ws 1     # ws1
+   ```
+
+6. **Shut down workspaces** with `./manage.sh stop-devenv`, either one by one or all at once.
+   You cannot shut down `ws0` if any other workspace is still running, since it's the worker-bearer.
+   Shared infrastructure will be cleaned up when the last workspace is stopped.
+
+Optional: watch Serena's activity in its dashboard
+(<http://localhost:14182> for ws0, <http://localhost:24182> for ws1, etc.).
+
+[^cfg]: One-time, if you don't already have it: set
+`penpotFlags = "enable-mcp"` in `frontend/resources/public/js/config.js`
+(gitignored; create if missing).
 
 ## Capabilities
 
@@ -32,7 +87,6 @@ with a comprehensive toolbox for Penpot development:
 * **Serena MCP Server** provides code intelligence tools with support for Clojure and TypeScript.
   Its memory system is used to organise project knowledge in a context-efficient manner.
 * **Playwright MCP Server** provides tools for browser remote control.
-* (optional) **GitHub MCP Server** provides tools for interacting with GitHub (issue, PRs, etc.)
 
 Equipped with the tools provided by these MCP servers, the agent can fully close the development loop,
 i.e. it can ...
@@ -47,122 +101,247 @@ i.e. it can ...
 * test the changes in the live Penpot instance, and
 * create commits and PRs resolving the issue.
 
-## Configuring and Starting the Agentic DevEnv
+## The flow in detail
 
-**First-Time Setup: Building the Image.** If you are starting the agentic DevEnv for the first time, you need to build
-the updated docker image, adding support for agentic tools:
+### First-time setup
 
-```bash
-./manage.sh build-devenv --local
-```
-
-**Enable the Penpot MCP Connection in the Frontend.**
-The agentic DevEnv relies on a connection between the Penpot frontend and the Penpot MCP server
-being established automatically.
-Edit the file `frontend/resources/public/js/config.js`,
-creating it if it does not exist, and make sure the `penpotFlags` variable contains the
-`enable-mcp` flag.
+**The MCP frontend flag.** Edit `frontend/resources/public/js/config.js`
+(create it if missing) and ensure `penpotFlags` contains `enable-mcp`:
 
 ```javascript
 var penpotFlags = "enable-mcp";
 ```
 
-**Running the DevEnv in Agentic Mode.** Start the DevEnv in agentic mode with:
+The file is gitignored and lives in the live repo only. On every
+`run-devenv-agentic` call it is read directly for ws0; for wsN (N ≥ 1) it is
+copied into the workspace clone on the **initial** sync only - subsequent
+`--sync` passes leave the workspace's copy alone so per-workspace
+customisations survive. `run-devenv-agentic` refuses to start if the file is
+missing.
 
-```bash
-./manage.sh run-devenv-agentic
-```
-
-## Opening Penpot with Remote Debugging & MCP Enabled
-
-**Enable Remote Debugging in Your Browser.**
-Penpot needs to be opened in a browser that has remote debugging enabled.
-In Chromium-based browsers (such as Google Chrome, Opera, Vivaldi, etc.),
-this can be achieved by launching the browser with the `--remote-debugging-port` argument.
-For most newer browsers, you will also need to specify a user data directory,
-as using debugging with your regular browser profile is disallowed for security reasons.
+**Browser remote debugging.** The Playwright MCP server drives a real
+browser instance over the Chrome DevTools protocol. To enable it, launch a
+Chromium-based browser (Chrome, Vivaldi, Opera, …) with the
+`--remote-debugging-port` flag and a separate user-data directory:
 
 ```bash
 google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-debug-profile"
 ```
 
-This enables the Playwright MCP server to connect to the browser and control it.
-Verify that debugging was enabled correctly by navigating to `http://127.0.0.1:9222/json/version`.
-If you change the port, adjust the MCP server configuration accordingly (see below).
-Note: For security reasons, you should not enable remote debugging with a profile
-that you use for regular browsing activities.
+Verify it works by visiting `http://127.0.0.1:9222/json/version`. If you
+change the port, update the Playwright MCP entry in `.devenv/shared/*.json`
+accordingly. For security reasons, do not enable remote debugging on the
+profile you use for regular browsing.
 
-**Open Penpot with the MCP Integration Enabled.**
-The Penpot instance in the DevEnv can be accessed at [https://localhost:3449](https://localhost:3449).
-Once logged in, navigate to your account settings, click on "Integrations" in the sidebar, and enable the "MCP Server" toggle.
-Note: You do not need to use the generated key (or the provided URL), as the MCP server in the agentic DevEnv is running in single-user mode and does not require authentication.
+**Enable the MCP integration in Penpot.** The Penpot UI has a per-account
+MCP toggle. After logging into your Penpot instance at
+[https://localhost:3449](https://localhost:3449), open account settings,
+click "Integrations" in the sidebar, and enable the "MCP Server" toggle.
+The agentic DevEnv runs the MCP server in single-user mode, so the
+generated key and proxied URL printed in the UI are *not* needed - only the
+toggle itself matters.
 
-## Configuring Your AI Client
+**(Optional) custom devenv image.** Only needed if you want to modify the
+devenv image itself (add a tool, change a base layer):
 
-Your AI client needs to be configured to connect to the MCP servers that collectively provide the agent with the necessary tools for Penpot development.
+```bash
+./manage.sh build-devenv --local
+```
 
-Below, we exemplarily provide a JSON-based configuration snippet, using `mcp-remote` to wrap HTTP-based servers.
+The default `run-devenv-agentic` flow pulls the published image
+automatically, so regular users never run this.
 
-Most clients using JSON-based configuration (e.g. Copilot, JetBrains AI Assistant, Claude Desktop, Antigravity)
-will work when inserting the server entries below into the client's configuration file.
-If your client uses a different configuration format, extract the relevant information (i.e. server URLs or launch commands)
-and configure the servers appropriately, referring to the documentation of your client.
+### Bringing up workspaces
+
+```bash
+./manage.sh run-devenv-agentic \
+    [--ws N] [--sync] [--serena-context CTX] \
+    [--git-user-name NAME] [--git-user-email EMAIL]
+```
+
+Brings one agentic instance up. Errors out if the target is already running.
+
+`--ws N` (N ≥ 1) auto-starts ws0 first if it is not already up - ws0 is the
+worker-bearer and must be running whenever any wsN is. Per-instance ports
+are offset by `10000 × N` (ws1's MCP at `http://localhost:14401/mcp`, Serena
+MCP at `http://localhost:24181`, Serena dashboard at
+`http://localhost:24182`, etc.). `manage.sh` prints the full URL set on
+every bring-up so you don't compute offsets by hand. See the
+[Dev environment guide](./devenv.md) for the workspace lifecycle, `--sync`
+semantics, and stop ordering.
+
+**Git identity for agent commits.** Coding agents typically need to commit
+inside the devenv, so `run-devenv-agentic` wires a Git identity into the
+container's global config on every bring-up. By default it propagates the
+host's effective `git config user.{name,email}` (local repo override wins
+over `~/.gitconfig`, matching what `git commit` on the host would record).
+Override with `--git-user-name "Full Name"` / `--git-user-email
+you@example.com` when you want agent commits to carry an identity different
+from your normal one. Without either source the script warns and proceeds;
+commits inside the devenv will fail until you fix it. See the
+[Dev environment guide](./devenv.md#git-identity-inside-the-container) for
+the full mechanics.
+
+> **Note:** the MCP and Serena tmux windows are only added when the tmux
+> session is first created. If a workspace was already brought up with
+> `./manage.sh run-devenv` (non-agentic), stop it before re-running
+> agentically:
+>
+> ```bash
+> ./manage.sh stop-devenv
+> ./manage.sh run-devenv-agentic
+> ```
+
+### Launching an AI client
+
+The agentic environment supports any AI client, one just needs to set the right MCP config,
+see [manual configuration](#manual-ai-client-configuration) below. For some popular clients, the `manage.sh`
+CLI offers direct support through the following mechanism:
+
+Every `run-devenv-agentic` regenerates three MCP-client config files with
+the workspace's ports baked in; Codex is wired up at launch instead (see
+below):
+
+| Client | File | Loaded how |
+| ------ | ---- | ---------- |
+| Claude Code | `<workspace>/.devenv/mcp/claude-code.json` | `--mcp-config <file>` flag |
+| opencode | `<workspace>/.devenv/mcp/opencode.json` | `OPENCODE_CONFIG=<file>` env var |
+| VS Code Copilot | `<workspace>/.vscode/mcp.json` | Auto-discovered when opening the workspace |
+| Codex CLI | _(none written)_ | Injected as `-c mcp_servers.…` overrides by `start-coding-agent codex` |
+
+The files are committed templates + an `envsubst` pass; see
+[`.devenv/README.md`](../../../.devenv/README.md) for the full layout.
+
+`./manage.sh start-coding-agent <client> [--ws N] [...passthrough]`
+launches the chosen client against one workspace, `cd`'ing into the right
+directory and refusing to launch if the instance is not running:
+
+```bash
+./manage.sh start-coding-agent claude              # ws0
+./manage.sh start-coding-agent opencode --ws 1     # ws1
+./manage.sh start-coding-agent vscode              # opens VS Code on ws0
+./manage.sh start-coding-agent codex --ws 2        # ws2
+```
+
+A given AI client session drives **exactly one workspace**, so running N
+parallel workspaces typically means running N AI client sessions, each
+pointed at a different workspace's ports.
+
+What each launcher does:
+
+* **Claude Code** is started with `--mcp-config .devenv/mcp/claude-code.json`,
+  which is **additive** - your existing global Claude Code MCP entries stay
+  available alongside the three entries we ship (Penpot MCP, Serena MCP,
+  Playwright). To shadow one of our entries with a private one, install it
+  under Claude Code's local scope (`claude mcp add --scope local …`); local
+  wins over `--mcp-config`.
+* **opencode** is started with `OPENCODE_CONFIG=.devenv/mcp/opencode.json`.
+  opencode's precedence chain is *global → `OPENCODE_CONFIG` → project*, so
+  the file we generate **overrides** entries with the same name in your
+  global config. To override our entries in turn, drop a personal
+  `opencode.json` at the repo root - it's gitignored on purpose.
+* **VS Code Copilot** - `code "$workspace"` opens VS Code on the workspace.
+  Copilot loads both your user-profile MCP config and the workspace's
+  `.vscode/mcp.json`. That workspace file is **deep-merged** rather than
+  overwritten: on ws0 (where it *is* the live repo's own file) any servers you
+  added survive, and only our three (Penpot MCP, Serena MCP, Playwright) are
+  rewritten to the current ports; on ws1+ it is created from scratch. To shadow
+  one of ours, add a same-named entry in your user profile - it wins.
+* **Codex CLI** - `codex` is exec'd from the workspace dir with our servers
+  passed as `-c mcp_servers.<name>....` overrides built from the committed
+  templates. **Nothing is written to `.codex/config.toml`**, so your own
+  project- or user-level Codex config is left untouched (and no "trusted
+  project" prompt is involved for our servers). Because `-c` is Codex's
+  highest-precedence layer, our entries win over a same-named server in your
+  config; to override one, append your own `-c` after the client name
+  (`... start-coding-agent codex -- -c 'mcp_servers.penpot.url="…"'`) - the
+  later `-c` wins.
+
+## Manual AI-client configuration
+
+The `start-coding-agent` launcher covers Claude Code, opencode, VS Code
+Copilot, and the Codex CLI. For any other client (JetBrains AI Assistant,
+Claude Desktop, Antigravity, …), or if you prefer to wire things up
+yourself, configure the MCP servers in your client's native format using
+the URLs below.
+
+The Penpot and Serena URLs for the workspace you want to target are printed
+by `manage.sh` every time it brings an instance up; copy them straight from
+that output. The mechanical rule is `port = base + 10000 × N` for `wsN`,
+with bases `4401` (Penpot MCP) and `14181` (Serena MCP). Playwright is not
+workspace-scoped - it connects to your local browser, so the same entry
+works for every client.
+
+### Project-level MCP config files (Claude Code, opencode - manual path)
+
+If you'd rather not go through the launcher, both Claude Code and opencode
+support project-level MCP config files that **merge with** the developer's
+global config:
+
+* **Claude Code** reads `.mcp.json` at the project root. Local scope
+  (`claude mcp add --scope local …`) overrides project scope.
+* **opencode** reads `opencode.json` at the project root (or any ancestor
+  Git directory). Configs are merged in the order *global → `OPENCODE_CONFIG`
+  → project*.
+
+The schemas differ between the two, so a workspace supporting both ships
+both files. For multi-workspace work, edit the port numbers in each
+workspace's copy once to match its offset.
+
+### Example configuration
+
+Below is a JSON-based configuration snippet in Claude Code's `mcpServers`
+schema, targeting `ws0` (main), using `mcp-remote` to wrap HTTP-based
+servers. To target a different workspace, substitute the Penpot MCP and
+Serena MCP URLs with the ones for that workspace.
+
+For clients using a different configuration format, extract the relevant
+information (server URLs or launch commands) and configure the servers
+appropriately, referring to your client's documentation.
 
 ```json
 {
   "mcpServers": {
-    "penpot": {
+    "penpot-ws0": {
       "command": "npx",
       "args": ["-y", "mcp-remote", "http://localhost:4401/mcp", "--allow-http" ]
     },
-    "serena-devenv": {
+    "serena-ws0-devenv": {
       "command": "npx",
-      "args": ["-y", "mcp-remote", "http://localhost:14281/mcp", "--allow-http"]
+      "args": ["-y", "mcp-remote", "http://localhost:14181/mcp", "--allow-http"]
     },
     "playwright": {
       "command": "npx",
       "args": ["@playwright/mcp@latest", "--cdp-endpoint=http://127.0.0.1:9222"]
-    },
-    "github": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "TODO_your_token"
-      }
     }
   }
 }
 ```
 
 **Penpot MCP Server**
-* The URL above connects directly to the server in the DevEnv, which runs in single-user mode.
-  You do not need to use the proxied URL or the user token that is provided by the Penpot UI.
+* The URL above connects directly to the server in the DevEnv, which runs
+  in single-user mode. You do not need to use the proxied URL or the user
+  token that is provided by the Penpot UI.
 
 **Serena MCP Server**
-* You can access Serena's dashboard at [http://localhost:14282](http://localhost:14282)
-
-**GitHub MCP Server**
-* The use of this MCP server is optional. (Direct shell access to GitHub CLI can be used alternatively.)
-* You need to provide a personal access token (PAT) with appropriate permissions:
-  * Create a token in your GitHub account settings [here](https://github.com/settings/personal-access-tokens).
-  * Choose the right resource owner: As a member of the `penpot` organisation, be sure to create a token where the resource owner is the organisation.
-    Otherwise, you will not be able to create pull requests or issues in the `penpot/penpot` repository.
-  * Grant the necessary permissions, e.g. read and write access to issues and pull requests.
+* The matching Serena dashboard lives on the next port (`14182` for ws0,
+  `24182` for ws1, …) and is also printed by `manage.sh` on startup.
 
 ## Working on Development Tasks
 
-After having made the configuration changes, restart your AI client.
-All four MCP servers should now be running and accessible to your client.
+After having made the configuration changes, restart your AI client. The
+configured MCP servers should now be running and accessible to your client.
 
-The agent's entrypoint for development is an activation of the `penpot` project with Serena.
-Start by instructing your agent as follows,
+The agent's entrypoint for development is an activation of the `penpot`
+project with Serena. Start by instructing your agent as follows,
 
 > Activate project penpot.
 
-and it should retrieve fundamental project information,
-expecting further instructions on what to do.
+and it should retrieve fundamental project information, expecting further
+instructions on what to do.
 
-**Always start your first prompt with these activation instructions**, as this bootstraps the agent's context.
+**Always start your first prompt with these activation instructions**, as
+this bootstraps the agent's context.
 
 ### Checking MCP Server Operability
 
diff --git a/docs/technical-guide/developer/devenv.md b/docs/technical-guide/developer/devenv.md
index 0443466e03..88ae8db6ca 100644
--- a/docs/technical-guide/developer/devenv.md
+++ b/docs/technical-guide/developer/devenv.md
@@ -45,13 +45,153 @@ This is an incomplete list of devenv related subcommands found on
 manage.sh script:
 
 ```bash
-./manage.sh build-devenv-local # builds the local devenv docker image (called by run-devenv automatically when needed)
-./manage.sh start-devenv       # starts background running containers
-./manage.sh run-devenv         # enters to new tmux session inside of one of the running containers
-./manage.sh stop-devenv        # stops background running containers
-./manage.sh drop-devenv        # removes all the containers, volumes and networks used by the devenv
+./manage.sh build-devenv --local # builds the local devenv docker image
+./manage.sh start-devenv         # brings up the shared infra + ws0 in background
+./manage.sh run-devenv           # ws0 with non-agentic tmux, attached (legacy alias)
+./manage.sh run-devenv-agentic   # one agentic instance; --ws to target ws1+; see below
+./manage.sh attach-devenv        # re-attaches to the tmux session of a running instance
+./manage.sh stop-devenv          # stops one instance (or --all); infra stops with the last
+./manage.sh drop-devenv          # removes containers (data volumes preserved)
 ```
 
+### Parallel workspaces
+
+The devenv runs as separate compose projects: shared infra (`penpotdev-infra`:
+Postgres, MinIO, mailer, LDAP) plus one `penpotdev-wsN` project per runtime
+instance. `ws0` (a.k.a. `main`) binds the live repo; `ws1+` bind clones the
+developer maintains explicitly under `${PENPOT_WORKSPACES_DIR}/wsN/`
+(default `~/.penpot/penpot_workspaces/`).
+
+Each call to `run-devenv-agentic` brings up one instance, and ws0 is always
+running whenever any ws1+ is — `--ws N` (N≥1) auto-starts ws0 first if it
+isn't already up:
+
+```bash
+./manage.sh run-devenv-agentic           # main (ws0)
+./manage.sh run-devenv-agentic --ws 1    # ws0 if needed, then ws1
+./manage.sh run-devenv-agentic --ws 2 --sync   # ws2, re-seeding from the live repo
+```
+
+Starting an instance that is already running is an error. `--sync` is only
+valid for `ws1+`; on ws0 it errors out. When a `ws1+` workspace directory
+does not exist yet, the first start syncs it implicitly from the live repo.
+Otherwise the workspace contents are left untouched unless `--sync` is passed
+again. Live-repo Git in a fragile state (rebase / merge / cherry-pick /
+`index.lock`) blocks all syncs.
+
+`frontend/resources/public/js/config.js` (which is gitignored and configures
+the frontend's MCP flag) is copied into each workspace on its initial sync
+only. After that the developer maintains it in each workspace; subsequent
+`--sync` runs leave the workspace copy alone.
+
+Stopping mirrors the start invariant — ws0 is the last to stop, and shared
+infra stops with it:
+
+```bash
+./manage.sh stop-devenv --ws 1           # stops ws1; ws0 + infra stay up
+./manage.sh stop-devenv                  # stops ws0 + infra; errors if ws1+ still running
+./manage.sh stop-devenv --all            # stops every ws1+ first, then ws0 + infra
+```
+
+Host ports are offset by `10000 × N`:
+
+| Service | ws0 | ws1 | ws2 |
+|---|---|---|---|
+| Penpot UI (HTTPS) | `https://localhost:3449` | `https://localhost:13449` | `https://localhost:23449` |
+| MCP HTTP stream | `http://localhost:4401/mcp` | `http://localhost:14401/mcp` | `http://localhost:24401/mcp` |
+| Serena MCP | `http://localhost:14181` | `http://localhost:24181` | `http://localhost:34181` |
+
+Container-internal ports stay fixed. Target a specific instance with
+`--ws N` on `attach-devenv`, `run-devenv-agentic`, `stop-devenv`,
+`start-coding-agent`, `run-devenv-shell`, and `isolated-shell`. `--ws`
+accepts a **non-negative integer only** — `--ws main` or `--ws ws1` is
+rejected, keeping the flag shape uniform across commands. `run-devenv` is
+ws0-only and takes no workspace flag. `run-devenv-agentic` also accepts
+`--serena-context CTX` and `--git-user-name NAME` / `--git-user-email
+EMAIL` (see below).
+
+Configuration lives in one tracked file, `docker/devenv/defaults.env` (the
+ws0 baseline); `ws1+` values (offset ports, `wsN` container/volume names) are
+derived and injected automatically, so there is no per-instance file to edit.
+
+### Git identity inside the container
+
+`run-devenv-agentic` wires a Git author identity into the container's
+**global** git config (`git config --global user.{name,email}`) so commits
+made from inside the devenv carry a real author/committer. Without this,
+the container would commit as the unconfigured `penpot@<container>`
+fallback — usable but useless for review.
+
+The values come from `--git-user-name NAME` / `--git-user-email EMAIL`
+when passed, or from your host's effective `git config user.{name,email}`
+otherwise. "Effective" here means the values plain `git config user.X`
+returns at the working directory `manage.sh` is invoked from — local
+(`<repo>/.git/config`) overrides global (`~/.gitconfig`), matching what
+`git commit` on the host would record. If neither is available the script
+prints a warning and continues — commits will fail inside the container
+until you set an identity. The values are applied every time
+`run-devenv-agentic` brings an instance up (idempotent), so re-running
+with different flags is the way to change the in-container identity.
+
+### Shared state and workers
+
+All instances share one Penpot database and one MinIO bucket; users, teams,
+files, and MCP tokens are visible from every instance. Per-instance Valkey
+keeps msgbus Pub/Sub channels (collab broadcasts, team-org notifications,
+file-summary cache, rate-limit counters) isolated.
+
+Background workers (`enable-backend-worker`) run only on ws0 — ws1+ overlays
+disable it. ws1+ RPC handlers still enqueue tasks into the shared Postgres
+`task` table; ws0's dispatcher claims them via `FOR UPDATE SKIP LOCKED` and
+runs them against the shared DB and MinIO. The "ws0 always up when ws1+ is
+up" invariant exists for this reason: it keeps a single worker-bearer and
+avoids the multi-instance cron-dedup race (the lock on `scheduled_task` is
+released when the task body finishes, so two cron timers firing the same
+scheduled instant with a gap larger than the body's runtime can both
+execute it).
+
+### Upgrading from a pre-parallel devenv
+
+The devenv compose configuration has been split into two files and reorganized
+into separate compose projects per runtime instance:
+
+- `docker/devenv/docker-compose.infra.yml` (Postgres, MinIO, mailer, LDAP)
+  runs under the compose project `penpotdev-infra`.
+- `docker/devenv/docker-compose.main.yml` (one main container + its Valkey)
+  runs once per runtime instance under `penpotdev-ws0`, `penpotdev-ws1`, ….
+- Both projects join the external Docker network `penpot_shared`, created
+  idempotently by `manage.sh`.
+- Configuration lives in `docker/devenv/defaults.env` (the ws0 baseline);
+  ws1+ overrides are computed and injected at compose time.
+
+If you had the devenv running on the previous single-project (`penpotdev`)
+layout, leftover containers and the auto-generated `penpotdev_default`
+network must be removed before bringing the new ws0 instance up. The named
+data volumes (`penpotdev_postgres_data_pg16`, `penpotdev_minio_data`,
+`penpotdev_user_data`, `penpotdev_valkey_data`) are pinned by explicit
+`name:` entries in the new compose files and are preserved through the
+transition — your Postgres DB, MinIO objects, and home cache survive.
+
+One-time cleanup, then bring up ws0:
+
+```bash
+# Stop and remove the old single-project containers (data volumes stay).
+docker stop penpot-devenv-main penpot-devenv-valkey 2>/dev/null
+docker rm   penpotdev-postgres-1 penpotdev-minio-1 penpotdev-minio-setup-1 \
+            penpotdev-mailer-1   penpotdev-ldap-1 \
+            penpot-devenv-main   penpot-devenv-valkey 2>/dev/null
+
+# Remove the orphaned auto-generated network.
+docker network rm penpotdev_default 2>/dev/null
+
+# Bring up infra + ws0 under the new project layout.
+./manage.sh run-devenv-agentic
+```
+
+After the cleanup, normal `./manage.sh start-devenv` / `run-devenv` /
+`run-devenv-agentic` commands work against the new layout. The legacy
+`penpotdev` compose project is no longer used.
+
 Having the container running and tmux opened inside the container,
 you are free to execute commands and open as many shells as you want.
 
diff --git a/exporter/scripts/run b/exporter/scripts/run
index 4bb272fc6a..a7f8836f74 100755
--- a/exporter/scripts/run
+++ b/exporter/scripts/run
@@ -3,4 +3,8 @@
 SCRIPT_DIR=$(dirname $0);
 source $SCRIPT_DIR/../../backend/scripts/_env;
 
+if [ -f $SCRIPT_DIR/../../backend/scripts/_env.local ]; then
+    source $SCRIPT_DIR/../../backend/scripts/_env.local;
+fi
+
 exec node target/app.js
diff --git a/exporter/scripts/wait-and-start.sh b/exporter/scripts/wait-and-start.sh
index f9638eb06d..53d1bc73f0 100755
--- a/exporter/scripts/wait-and-start.sh
+++ b/exporter/scripts/wait-and-start.sh
@@ -3,6 +3,10 @@
 SCRIPT_DIR=$(dirname $0);
 source $SCRIPT_DIR/../../backend/scripts/_env;
 
+if [ -f $SCRIPT_DIR/../../backend/scripts/_env.local ]; then
+    source $SCRIPT_DIR/../../backend/scripts/_env.local;
+fi
+
 bb -i '(babashka.wait/wait-for-port "localhost" 9630)';
 bb -i '(babashka.wait/wait-for-path "target/app.js")';
 sleep 2;
diff --git a/frontend/shadow-cljs.edn b/frontend/shadow-cljs.edn
index fadcb4131f..4b2dea2b38 100644
--- a/frontend/shadow-cljs.edn
+++ b/frontend/shadow-cljs.edn
@@ -9,8 +9,14 @@
   {:target :esm
    :output-dir "resources/public/js/"
    :asset-path "/js"
-   :devtools {:watch-dir "resources/public"
-              :reload-strategy :full}
+   ;; :devtools is dev-only, so it lives under :dev -- shadow merges that map
+   ;; for `watch`/`compile` but not `release`, keeping :devtools-url out of
+   ;; release entirely (shadow spec-checks it as non-empty-string? whenever the
+   ;; key is present, even in release). In the devenv SHADOW_SERVER_URL is
+   ;; always set per workspace (see defaults.env / manage.sh).
+   :dev {:devtools {:watch-dir "resources/public"
+                    :reload-strategy :full
+                    :devtools-url #shadow/env ["SHADOW_SERVER_URL" :default ""]}}
    :build-options {:manifest-name "manifest.json"}
    :modules
    {:shared
@@ -86,9 +92,11 @@
   {:target :browser
    :output-dir "resources/public/js/worker/"
    :asset-path "/js/worker"
-   :devtools {:browser-inject :main
-              :watch-dir "resources/public"
-              :reload-strategy :full}
+   ;; Dev-only; see the :main build above for why :devtools lives under :dev.
+   :dev {:devtools {:devtools-url #shadow/env ["SHADOW_SERVER_URL" :default ""]
+                    :browser-inject :main
+                    :watch-dir "resources/public"
+                    :reload-strategy :full}}
    :build-options {:manifest-name "manifest.json"}
    :modules
    {:main
diff --git a/manage.sh b/manage.sh
index 96581325db..38c5edc415 100755
--- a/manage.sh
+++ b/manage.sh
@@ -2,7 +2,56 @@
 
 export ORGANIZATION="penpotapp";
 export DEVENV_IMGNAME="$ORGANIZATION/devenv";
-export DEVENV_PNAME="penpotdev";
+export DEVENV_NETWORK="penpot_shared";
+export DEVENV_DEFAULTS_FILE="docker/devenv/defaults.env";
+
+# Load instance configuration (project name, container names, ports, runtime
+# config). Single source of truth for the devenv; consumed by both docker
+# compose (via --env-file) and the shell logic below. Hard dependency — abort
+# loudly if it's missing or unreadable.
+#
+# Host-shell env wins over file values: a value already set in the parent
+# environment is preserved. This matches docker compose's own precedence rule
+# for --env-file (so substitution-time and shell-time agree).
+if [ ! -r "$DEVENV_DEFAULTS_FILE" ]; then
+    echo "manage.sh: cannot read $DEVENV_DEFAULTS_FILE" >&2
+    exit 1
+fi
+while IFS='=' read -r __key __value; do
+    [[ -z "$__key" || "$__key" =~ ^[[:space:]]*# ]] && continue
+    if [ -z "${!__key+x}" ]; then
+        export "$__key=$__value"
+    fi
+done < "$DEVENV_DEFAULTS_FILE"
+unset __key __value
+
+# Source path for the workspace bind mount; consumed by docker-compose.main.yml.
+# ws0 binds the live repo at $PWD; ws1+ override this in their overlay env file.
+export PENPOT_SOURCE_PATH="${PENPOT_SOURCE_PATH:-$PWD}"
+
+# Base directory under which non-main workspace clones live (one subdir per
+# wsN, N>=1). Documented in defaults.env; default lives here so $HOME expands.
+export PENPOT_WORKSPACES_DIR="${PENPOT_WORKSPACES_DIR:-$HOME/.penpot/penpot_workspaces}"
+
+# Port allocation for parallel instances. Each wsN reserves a stride-wide port
+# block starting at N*stride; ws0 sits at offset 0, so a per-service base port
+# IS ws0's published port. To keep a single source of truth, the bases are
+# derived from the ws0 values sourced from defaults.env above rather than
+# duplicated here -- this makes it impossible for ws0's compose substitution and
+# the ws1+ offset arithmetic to drift apart. `:?` aborts loudly if defaults.env
+# is missing one. Consumed by instance-env-overrides (the values injected into
+# the per-instance compose env) and print-instance-info (the startup URLs).
+PENPOT_INSTANCE_PORT_STRIDE=10000
+PENPOT_PORT_BASE_PUBLIC=${PENPOT_PUBLIC_HTTP_PORT:?missing in defaults.env}
+PENPOT_PORT_BASE_MCP=${PENPOT_MCP_SERVER_PORT:?missing in defaults.env}
+PENPOT_PORT_BASE_MCP_REPL=${PENPOT_MCP_REPL_PORT:?missing in defaults.env}
+PENPOT_PORT_BASE_SERENA=${SERENA_EXTERNAL_PORT:?missing in defaults.env}
+PENPOT_PORT_BASE_SERENA_DASHBOARD=${SERENA_DASHBOARD_EXTERNAL_PORT:?missing in defaults.env}
+
+# Per-instance values like PENPOT_REDIS_URI must live in each instance's env
+# file (not in this shell), because docker compose's --env-file mechanism
+# lets a per-instance overlay override the baseline while the shell env
+# would otherwise shadow both for every project.
 
 export CURRENT_USER_ID=$(id -u);
 export CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD);
@@ -17,6 +66,50 @@ export JAVA_OPTS=${JAVA_OPTS:-"-Xmx1000m -Xms50m"};
 
 set -e
 
+# ----------------------------------------------------------------------------
+# Function map
+#
+# Utility helpers
+#   print-current-version, setup-buildx, put-license-file
+#
+# Devenv image lifecycle
+#   build-devenv, pull-devenv, pull-devenv-if-not-exists
+#
+# Devenv compose plumbing (used by every *-devenv command below)
+#   ensure-devenv-network   create the external 'penpot_shared' network
+#   infra-compose           wrap 'docker compose' for the shared-infra project
+#   instance-compose        wrap 'docker compose' for one instance's main
+#                           project, injecting that instance's overrides
+#   instance-env-overrides  the per-instance KEY=VALUE overrides (ws1+)
+#   devenv-main-container   resolve the 'main' container id via compose ps
+#   devenv-main-running     true if 'main' is up
+#
+# Devenv lifecycle (operate on the whole compose project)
+#   start-devenv, create-devenv, stop-devenv, drop-devenv, log-devenv
+#
+# Devenv interactive entry points (all operate on the running 'main' container)
+#   run-devenv-tmux         starts 'main' if needed and execs start-tmux.sh
+#                           interactively (this is what 'run-devenv' resolves to)
+#   run-devenv-agentic      same as run-devenv-tmux but enables MCP + Serena;
+#                           also regenerates .devenv/mcp/<tool>.json for the
+#                           target workspace (via write-instance-mcp-configs)
+#   attach-devenv           pure attach to the existing tmux session; fails
+#                           fast if the devenv or session is missing
+#   start-coding-agent      launches Claude Code or opencode against the
+#                           current workspace's generated MCP config
+#   run-devenv-shell        starts 'main' if needed and execs a bash shell
+#   run-devenv-isolated-shell  one-shot 'docker run' (NOT compose) against the
+#                           project user_data volume and the current PWD; used
+#                           for ad-hoc operations that should not touch a
+#                           running devenv
+#
+# Production build pipeline
+#   build                   one-shot 'docker run' that invokes a per-module
+#                           build script inside the devenv image
+#   build-<mod>-bundle      project a module's build output into ./bundles/
+#   build-<mod>-docker-image  package a bundle into a release docker image
+# ----------------------------------------------------------------------------
+
 ARCH=$(uname -m)
 
 if [[ "$ARCH" == "x86_64" || "$ARCH" == "amd64" || "$ARCH" == "i386" || "$ARCH" == "i686" ]]; then
@@ -80,31 +173,434 @@ function pull-devenv-if-not-exists {
     fi
 }
 
+function ensure-devenv-network {
+    docker network inspect "$DEVENV_NETWORK" >/dev/null 2>&1 || docker network create "$DEVENV_NETWORK" >/dev/null
+}
+
+# Compose-project plumbing for the parallel-workspaces layout.
+#
+# - Shared infrastructure (postgres, minio, mailer, ldap, minio-setup) runs
+#   under project `penpotdev-infra`.
+# - Each runtime instance (ws0, ws1, ...) runs its own main + valkey under
+#   project `penpotdev-wsN`. ws0 uses the `defaults.env` baseline as-is; ws1+
+#   override the per-instance values by injecting them as environment
+#   variables -- see instance-env-overrides (no files are written).
+# `env -i` strips the ambient shell before invoking docker compose, then we
+# re-inject exactly what compose needs. The stripping matters because
+# defaults.env is sourced into manage.sh's own shell at startup, so otherwise
+# those stale values would leak into substitution. And because Docker Compose
+# gives shell-env precedence over --env-file, the re-injected per-instance
+# overrides cleanly override the defaults.env baseline. Re-injected: HOME/PATH
+# (tooling), CURRENT_USER_ID/PENPOT_SOURCE_PATH (always per-call), and for ws1+
+# the instance-env-overrides block.
+function infra-compose {
+    env -i HOME="$HOME" PATH="$PATH" PWD="$PWD" \
+        docker compose -p penpotdev-infra \
+            --env-file "$DEVENV_DEFAULTS_FILE" \
+            -f docker/devenv/docker-compose.infra.yml \
+            "$@"
+}
+
+function instance-compose {
+    local instance="$1"; shift
+    local source_path
+    local -a overrides=()
+    if [[ "$instance" == "ws0" ]]; then
+        source_path="$PWD"
+    else
+        source_path="$(workspace-path "$instance")"
+        mapfile -t overrides < <(instance-env-overrides "$instance")
+    fi
+    env -i HOME="$HOME" PATH="$PATH" PWD="$PWD" \
+        CURRENT_USER_ID="${CURRENT_USER_ID:-$(id -u)}" \
+        PENPOT_SOURCE_PATH="$source_path" \
+        "${overrides[@]}" \
+        docker compose -p "penpotdev-${instance}" \
+            --env-file "$DEVENV_DEFAULTS_FILE" \
+            -f docker/devenv/docker-compose.main.yml \
+            "$@"
+}
+
+# Names of currently-running parallel instances (ws0, ws1, ...).
+function list-running-instances {
+    docker ps --format '{{.Label "com.docker.compose.project"}}' 2>/dev/null \
+        | sort -u \
+        | grep -oE '^penpotdev-ws[0-9]+$' \
+        | sed 's/^penpotdev-//' \
+        || true
+}
+
+function devenv-main-container {
+    local instance="${1:-ws0}"
+    # For ws1+, skip compose if the workspace clone doesn't exist yet — the
+    # instance has never been set up, so there is no container to find.
+    if [[ "$instance" != "ws0" && ! -d "$(workspace-path "$instance")" ]]; then
+        return 0
+    fi
+    instance-compose "$instance" ps -q main 2>/dev/null
+}
+
+function devenv-main-running {
+    local instance="${1:-ws0}"
+    local container
+    container=$(devenv-main-container "$instance")
+    [[ -n "$container" ]] && [[ "$(docker inspect -f '{{.State.Running}}' "$container" 2>/dev/null)" = "true" ]]
+}
+
+# Bring shared infra up and block until minio-setup has provisioned the
+# shared MinIO user/policy. Idempotent: a second call when everything is
+# already up returns immediately.
+function ensure-infra-up {
+    infra-compose up -d
+    local setup_container
+    setup_container=$(infra-compose ps -aq minio-setup 2>/dev/null)
+    if [[ -n "$setup_container" ]]; then
+        docker wait "$setup_container" >/dev/null 2>&1 || true
+    fi
+}
+
+# Refuse to sync workspaces if the live repo is in a fragile Git state.
+# Copying a partial rebase/merge/cherry-pick into all workspaces would leave
+# every instance in the same broken state.
+function assert-clean-git-state {
+    local fragile=""
+    [ -d .git/rebase-apply ] && fragile="$fragile rebase-apply"
+    [ -d .git/rebase-merge ] && fragile="$fragile rebase-merge"
+    [ -f .git/MERGE_HEAD ]    && fragile="$fragile merge"
+    [ -f .git/CHERRY_PICK_HEAD ] && fragile="$fragile cherry-pick"
+    [ -f .git/index.lock ]    && fragile="$fragile index.lock"
+    if [[ -n "$fragile" ]]; then
+        echo "Live repo Git state is unsafe to copy into workspaces:$fragile" >&2
+        echo "Finish or abort the in-progress operation, then retry." >&2
+        return 1
+    fi
+}
+
+# Absolute path of the workspace directory for a non-ws0 instance.
+function workspace-path {
+    local instance="$1"
+    echo "${PENPOT_WORKSPACES_DIR}/${instance}"
+}
+
+# Echo the host port that <base> maps to for <instance>.
+function instance-port {
+    local instance="$1"
+    local base="$2"
+    local n=0
+    [[ "$instance" =~ ^ws([0-9]+)$ ]] && n="${BASH_REMATCH[1]}"
+    echo $(( base + n * PENPOT_INSTANCE_PORT_STRIDE ))
+}
+
+# Echo the per-instance Compose variable overrides for a ws1+ instance, one
+# KEY=VALUE per line, for instance-compose to inject into its `env -i` line.
+# Compose gives shell-env precedence over --env-file, so these override the
+# defaults.env baseline. Every value is a pure function of the instance number,
+# so nothing is persisted: they are recomputed on every compose invocation and
+# can never drift from this logic. ws0 has no overrides (it uses defaults.env
+# as-is) and is never passed here.
+#
+# Omitted on purpose: COMPOSE_PROJECT_NAME (set via compose's -p flag),
+# PENPOT_SOURCE_PATH (injected directly by instance-compose), and
+function instance-env-overrides {
+    local instance="$1"
+    local public mcp mcp_repl serena serena_dash
+    public=$(instance-port "$instance" "$PENPOT_PORT_BASE_PUBLIC")
+    mcp=$(instance-port "$instance" "$PENPOT_PORT_BASE_MCP")
+    mcp_repl=$(instance-port "$instance" "$PENPOT_PORT_BASE_MCP_REPL")
+    serena=$(instance-port "$instance" "$PENPOT_PORT_BASE_SERENA")
+    serena_dash=$(instance-port "$instance" "$PENPOT_PORT_BASE_SERENA_DASHBOARD")
+    printf '%s\n' \
+        "PENPOT_MAIN_CONTAINER_NAME=penpot-devenv-${instance}-main" \
+        "PENPOT_VALKEY_CONTAINER_NAME=penpot-devenv-${instance}-valkey" \
+        "PENPOT_VALKEY_HOSTNAME=penpot-devenv-${instance}-valkey" \
+        "PENPOT_USER_DATA_VOLUME=penpotdev_${instance}_user_data" \
+        "PENPOT_VALKEY_DATA_VOLUME=penpotdev_${instance}_valkey_data" \
+        "PENPOT_PUBLIC_URI=https://localhost:${public}" \
+        "PENPOT_REDIS_URI=redis://penpot-devenv-${instance}-valkey/0" \
+        "PENPOT_PUBLIC_HTTP_PORT=${public}" \
+        "PENPOT_MCP_SERVER_PORT=${mcp}" \
+        "PENPOT_MCP_REPL_PORT=${mcp_repl}" \
+        "SERENA_EXTERNAL_PORT=${serena}" \
+        "SERENA_DASHBOARD_EXTERNAL_PORT=${serena_dash}" \
+        "PENPOT_BACKEND_WORKER=false" \
+        "SHADOW_SERVER_URL=wss://localhost:${public}"
+}
+
+# Thin wrapper around .devenv/scripts/merge-mcp-config.py for the JSON clients
+# (Claude Code, opencode, VS Code). The script does the actual envsubst + JSON
+# deep-merge; see its docstring for the contract. ${PENPOT_MCP_PORT} /
+# ${SERENA_MCP_PORT} placeholders in the template are resolved from the
+# caller's environment. Any extra flags (e.g. --merge-into-existing for the VS
+# Code output) are forwarded verbatim.
+#
+# Codex deliberately has no wrapper here: it cannot load an MCP config from an
+# arbitrary file path, so instead of writing a file we inject our servers as
+# `-c` overrides built at launch time -- see start-coding-agent.
+function _merge-mcp-config-json {
+    local shared="$1" tpl="$2" out="$3" key="$4"; shift 4
+    python3 .devenv/scripts/merge-mcp-config.py \
+        --format json --key "$key" "$@" \
+        "$shared" "$tpl" "$out"
+}
+
+# Generate the per-workspace AI-client MCP config files by merging the
+# committed .devenv/shared/<tool>.* with the port-substituted
+# .devenv/templates/<tool>.*. Developers who want to override entries should
+# use the client's own override mechanism: Claude Code's local scope, a
+# project-level opencode.json, a VS Code user-profile entry, or a user-level
+# ~/.codex/config.toml.
+#
+# Generated paths per tool:
+#   <workspace>/.devenv/mcp/claude-code.json   loaded via --mcp-config; clean
+#                                              overwrite (dedicated gitignored
+#                                              file, no developer content)
+#   <workspace>/.devenv/mcp/opencode.json      loaded via OPENCODE_CONFIG=; same
+#   <workspace>/.vscode/mcp.json               auto-loaded by VS Code Copilot;
+#                                              DEEP-MERGED into any existing file
+#                                              so a developer's own entries on
+#                                              ws0 survive (ws0's file IS the
+#                                              live repo's; ws1+ start fresh).
+#                                              Ours win on name collision.
+#
+# Codex is intentionally NOT generated here. It cannot load an MCP config from
+# an arbitrary path, and writing the auto-discovered .codex/config.toml would
+# clobber the developer's project-level Codex config on ws0. Instead its
+# servers are injected as `-c` overrides at launch -- see start-coding-agent.
+function write-instance-mcp-configs {
+    local instance="$1"
+    local workspace
+    if [[ "$instance" == "ws0" ]]; then
+        workspace="$PWD"
+    else
+        workspace=$(workspace-path "$instance")
+    fi
+
+    local src_dir="$workspace/.devenv"
+    if [[ ! -d "$src_dir/shared" || ! -d "$src_dir/templates" ]]; then
+        echo "[$instance] .devenv/shared or .devenv/templates missing under $workspace; skipping MCP config generation." >&2
+        return 0
+    fi
+
+    local mcp_dir="$src_dir/mcp"
+    mkdir -p "$mcp_dir" "$workspace/.vscode"
+
+    PENPOT_MCP_PORT=$(instance-port "$instance" "$PENPOT_PORT_BASE_MCP")
+    SERENA_MCP_PORT=$(instance-port "$instance" "$PENPOT_PORT_BASE_SERENA")
+    export PENPOT_MCP_PORT SERENA_MCP_PORT
+
+    _merge-mcp-config-json \
+        "$src_dir/shared/claude-code.json" \
+        "$src_dir/templates/claude-code.json" \
+        "$mcp_dir/claude-code.json" \
+        mcpServers
+    _merge-mcp-config-json \
+        "$src_dir/shared/opencode.json" \
+        "$src_dir/templates/opencode.json" \
+        "$mcp_dir/opencode.json" \
+        mcp
+    # VS Code's mcp.json is auto-discovered at a fixed path, so on ws0 it IS the
+    # developer's own project file -- deep-merge into it rather than overwriting.
+    # On ws1+ the path does not exist yet, so this writes it from scratch.
+    _merge-mcp-config-json \
+        "$src_dir/shared/vscode.json" \
+        "$src_dir/templates/vscode.json" \
+        "$workspace/.vscode/mcp.json" \
+        servers \
+        --merge-into-existing
+}
+
+# Seed (or re-seed) a workspace from the live repo, then switch it onto a
+# unique branch. Two-step sync:
+#   1. .git directory is rsync'd directly (so the workspace has its own
+#      clone with the developer's current commits / index).
+#   2. Working-tree files are enumerated by `git ls-files`, which is the
+#      only authoritative source for "what files belong in the working
+#      tree" (Git tracks files even when their parent directory matches
+#      a gitignore pattern, e.g. .clj-kondo/config.edn). Using rsync's
+#      gitignore filter directly misses those.
+# Gitignored caches already in the workspace (node_modules, target, etc.)
+# are left in place: no --delete on the working-tree pass.
+function sync-workspace {
+    local instance="$1"
+    if [[ "$instance" == "ws0" ]]; then
+        return 0
+    fi
+    assert-clean-git-state || return 1
+
+    local workspace
+    workspace=$(workspace-path "$instance")
+    mkdir -p "$workspace"
+
+    echo "[$instance] syncing workspace at $workspace ..."
+
+    # .git directory — direct mirror, including index, refs, hooks, etc.
+    rsync -a --delete "$PWD/.git/" "$workspace/.git/"
+
+    # Working-tree files: tracked + untracked-not-ignored. git ls-files
+    # speaks Git's actual semantics, including the "tracked overrides
+    # gitignore" rule. --files-from feeds the path list to rsync verbatim.
+    local files
+    files=$(mktemp)
+    git -C "$PWD" ls-files -z --cached --others --exclude-standard >"$files"
+    rsync -a --files-from="$files" --from0 "$PWD/" "$workspace/"
+    rm -f "$files"
+
+    # Initial seed of frontend/resources/public/js/config.js. The file is
+    # gitignored, so git ls-files would not list it, yet the agentic devenv
+    # needs it (enable-mcp flag). After the first sync the workspace copy
+    # belongs to the user — subsequent syncs leave it untouched.
+    local cfg="frontend/resources/public/js/config.js"
+    if [[ -f "$PWD/$cfg" && ! -f "$workspace/$cfg" ]]; then
+        install -D "$PWD/$cfg" "$workspace/$cfg"
+    fi
+
+    (
+        cd "$workspace"
+        git switch -C "${instance}/${CURRENT_BRANCH}" >/dev/null
+    )
+}
+
 function start-devenv {
     pull-devenv-if-not-exists $@;
+    ensure-devenv-network;
 
-    docker compose -p $DEVENV_PNAME -f docker/devenv/docker-compose.yaml up -d;
+    ensure-infra-up
+    instance-compose ws0 up -d
 }
 
 function create-devenv {
     pull-devenv-if-not-exists $@;
+    ensure-devenv-network;
 
-    docker compose -p $DEVENV_PNAME -f docker/devenv/docker-compose.yaml create;
+    infra-compose create
+    instance-compose ws0 create
 }
 
+# Stop instances. ws0 is the worker-bearer and must be the last one to stop;
+# shared infra is shut down together with ws0. Flags are mutually exclusive.
+#
+#   --ws N (N>=1)  stop just that workspace. Leaves ws0 and infra alone.
+#   --ws 0 | (no flag)  stop ws0 + shared infra. Refused if any ws1+ is running.
+#   --all          stop every wsN highest-first, then ws0, then infra.
 function stop-devenv {
-    docker compose -p $DEVENV_PNAME -f docker/devenv/docker-compose.yaml stop -t 2;
+    local target=""
+    local all=false
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ws)
+                target="$(parse-ws-integer "$2")" || return 1; shift 2;;
+            --all)
+                all=true; shift;;
+            *)
+                echo "stop-devenv: unknown argument '$1'" >&2
+                return 1;;
+        esac
+    done
+    if [[ -n "$target" && "$all" == "true" ]]; then
+        echo "stop-devenv: --ws and --all are mutually exclusive." >&2
+        return 1
+    fi
+
+    local running ws
+    running=$(list-running-instances)
+
+    if [[ "$all" == "true" ]]; then
+        # Highest wsN first, then ws0, then infra. ws0 stop also brings infra.
+        for ws in $(printf '%s\n' $running | grep -v '^ws0$' | sed 's/^ws//' | sort -rn | sed 's/^/ws/'); do
+            stop-instance "$ws"
+        done
+        if printf '%s\n' $running | grep -qx ws0; then
+            stop-instance ws0
+        fi
+        infra-compose down -t 2
+        return 0
+    fi
+
+    # Default target: ws0 (which also stops infra).
+    [[ -z "$target" ]] && target="ws0"
+
+    if [[ "$target" == "ws0" ]]; then
+        local non_main=""
+        for ws in $running; do
+            [[ "$ws" != "ws0" ]] && non_main="$non_main $ws"
+        done
+        if [[ -n "$non_main" ]]; then
+            echo "stop-devenv: cannot stop ws0 while other instances are running:${non_main}." >&2
+            echo "Stop them first (--ws N) or use --all." >&2
+            return 1
+        fi
+        if printf '%s\n' $running | grep -qx ws0; then
+            stop-instance ws0
+        else
+            echo "[ws0] not running."
+        fi
+        infra-compose down -t 2
+        return 0
+    fi
+
+    # --ws N (N>=1): stop just that instance, leave ws0 + infra up.
+    if printf '%s\n' $running | grep -qx "$target"; then
+        stop-instance "$target"
+    else
+        echo "[$target] not running."
+    fi
 }
 
+# drop-devenv shares stop-devenv's CLI and invariants exactly; the only
+# difference is that on a full teardown it also removes the devenv image
+# (forcing the next bring-up to re-pull/rebuild). Single-workspace drops
+# keep the image because the rest of the workspaces still depend on it.
+#
+#   --ws N (N >= 1)  delegate to stop-devenv; image is kept.
+#   --ws 0 | (none)  delegate to stop-devenv; image is removed.
+#   --all            delegate to stop-devenv; image is removed.
 function drop-devenv {
-    docker compose -p $DEVENV_PNAME -f docker/devenv/docker-compose.yaml down -t 2 -v;
+    # Parse args ourselves to decide whether the image gets removed.
+    # stop-devenv then re-parses the same flags and runs the actual stop.
+    local target=""
+    local all=false
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ws)
+                target="$(parse-ws-integer "$2")" || return 1; shift 2;;
+            --all)
+                all=true; shift;;
+            *)
+                echo "drop-devenv: unknown argument '$1'" >&2
+                return 1;;
+        esac
+    done
+    if [[ -n "$target" && "$all" == "true" ]]; then
+        echo "drop-devenv: --ws and --all are mutually exclusive." >&2
+        return 1
+    fi
 
-    echo "Clean old development image $DEVENV_IMGNAME..."
-    docker images $DEVENV_IMGNAME -q | awk '{print $3}' | xargs --no-run-if-empty docker rmi
+    local stop_args=()
+    [[ -n "$target" ]] && stop_args+=(--ws "${target#ws}")
+    [[ "$all" == "true" ]] && stop_args+=(--all)
+    stop-devenv "${stop_args[@]}" || return $?
+
+    # Image removal happens for the full-teardown paths only. A single-wsN
+    # (N >= 1) drop must keep the image since ws0 and any other wsN still
+    # rely on it.
+    if [[ -z "$target" || "$target" == "ws0" ]] || [[ "$all" == "true" ]]; then
+        echo "Clean old development image $DEVENV_IMGNAME..."
+        docker images $DEVENV_IMGNAME -q | xargs --no-run-if-empty docker rmi
+    fi
 }
 
 function log-devenv {
-    docker compose -p $DEVENV_PNAME -f docker/devenv/docker-compose.yaml logs -f --tail=50
+    local target="ws0"
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ws)
+                target="$(parse-ws-integer "$2")" || return 1; shift 2;;
+            *)
+                echo "log-devenv: unknown argument '$1'" >&2
+                return 1;;
+        esac
+    done
+    instance-compose "$target" logs -f --tail=50
 }
 
 function run-devenv-tmux {
@@ -117,72 +613,496 @@ function run-devenv-tmux {
             -e*)
                 extra_env_args+=(-e "${1#-e}"); shift;;
             *)
-                shift;;
+                echo "run-devenv: unknown argument '$1'" >&2
+                return 1;;
         esac
     done
 
-    if [[ ! $(docker ps -f "name=penpot-devenv-main" -q) ]]; then
+    if ! devenv-main-running ws0; then
         start-devenv
         echo "Waiting for containers fully start (5s)..."
-        sleep 5;
+        sleep 5
     fi
 
+    local container
+    container=$(devenv-main-container ws0)
     docker exec -ti \
         "${extra_env_args[@]}" \
-        penpot-devenv-main sudo -EH -u penpot PENPOT_PLUGIN_DEV=$PENPOT_PLUGIN_DEV /home/start-tmux.sh
+        "$container" sudo -EH -u penpot PENPOT_PLUGIN_DEV=$PENPOT_PLUGIN_DEV /home/start-tmux.sh
+}
+
+# Strict parser for --ws values. Accepts a bare integer in the supported
+# range (0..PENPOT_MAX_WS_INDEX) and returns the canonical "wsN" form.
+# Anything else fails fast. The upper bound exists because the host ports
+# computed for higher N overflow the 16-bit TCP port range:
+#   port = base + N * PENPOT_INSTANCE_PORT_STRIDE (10000)
+# With the current Serena bases (14181/14182), N = 5 still fits inside
+# 65535 (64181/64182) but N = 6 overflows (74181/74182), so the cap is 5.
+PENPOT_MAX_WS_INDEX=5
+function parse-ws-integer {
+    local raw="$1"
+    if [[ ! "$raw" =~ ^[0-9]+$ ]]; then
+        echo "Invalid --ws value: '$raw' (expected a non-negative integer, e.g. --ws 0, --ws 1, --ws 2)" >&2
+        return 1
+    fi
+    if (( raw > PENPOT_MAX_WS_INDEX )); then
+        echo "Invalid --ws value: '$raw' (max supported is --ws $PENPOT_MAX_WS_INDEX; higher indexes would overflow the 16-bit TCP port range)" >&2
+        return 1
+    fi
+    echo "ws$raw"
 }
 
 
+# Bring a single agentic instance up: compose up + detached tmux start with
+# MCP and Serena enabled. Workspace sync and env-file generation are the
+# caller's responsibility (run-devenv-agentic handles them for ws1+).
+function start-instance {
+    local instance="$1"
+    local serena_context="$2"
+    local git_user_name="${3:-}"
+    local git_user_email="${4:-}"
+
+    instance-compose "$instance" up -d --no-deps main redis
+
+    # Wait briefly for main to be reachable; the tmux session lives inside.
+    local container deadline
+    container=$(devenv-main-container "$instance")
+    deadline=$(( SECONDS + 30 ))
+    while ! docker inspect -f '{{.State.Running}}' "$container" 2>/dev/null | grep -q true; do
+        [[ $SECONDS -ge $deadline ]] && {
+            echo "[${instance}] main container did not reach Running within 30s" >&2
+            return 1
+        }
+        sleep 1
+    done
+
+    # Seed the container's global git config from the values resolved on the
+    # host so commits made inside the devenv carry a real author/committer. Empty
+    # values are skipped — the host-identity warning is the caller's job.
+    if [[ -n "$git_user_name" ]]; then
+        docker exec "$container" sudo -u penpot git config --global user.name "$git_user_name"
+    fi
+    if [[ -n "$git_user_email" ]]; then
+        docker exec "$container" sudo -u penpot git config --global user.email "$git_user_email"
+    fi
+
+    # Detached tmux so callers don't block on attach. Agentic mode is the only
+    # mode here, so MCP and Serena are always on.
+    docker exec -d \
+        -e PENPOT_TMUX_ATTACH=false \
+        -e PENPOT_FLAGS="${PENPOT_FLAGS:-} enable-mcp" \
+        -e SERENA_ENABLED=true \
+        -e SERENA_CONTEXT="$serena_context" \
+        "$container" \
+        sudo -EH -u penpot PENPOT_PLUGIN_DEV="${PENPOT_PLUGIN_DEV:-}" /home/start-tmux.sh
+}
+
+# Stop and remove one instance's containers without touching its volumes or
+# its on-disk workspace directory (rule: never wipe data).
+function stop-instance {
+    local instance="$1"
+    instance-compose "$instance" down -t 2
+}
+
+# Print per-instance URLs (Penpot UI, MCP stream endpoint, Serena, attach
+# command) for one instance.
+function print-instance-info {
+    local instance="$1"
+    local public mcp serena serena_dash
+    public=$(instance-port "$instance" "$PENPOT_PORT_BASE_PUBLIC")
+    mcp=$(instance-port "$instance" "$PENPOT_PORT_BASE_MCP")
+    serena=$(instance-port "$instance" "$PENPOT_PORT_BASE_SERENA")
+    serena_dash=$(instance-port "$instance" "$PENPOT_PORT_BASE_SERENA_DASHBOARD")
+
+    # --ws takes a bare integer; ws0 is the default, so its flag is elided.
+    local n="${instance#ws}"
+    local ws_flag=""
+    [[ "$instance" != "ws0" ]] && ws_flag=" --ws ${n}"
+
+    echo
+    echo "[$instance]"
+    echo "  Penpot UI:           https://localhost:${public}"
+    echo "  MCP stream:          http://localhost:${mcp}/mcp"
+    echo "  Serena MCP:          http://localhost:${serena}"
+    echo "  Serena dashboard:    http://localhost:${serena_dash}"
+    echo "  Attach:              ./manage.sh attach-devenv${ws_flag}"
+    echo "  Coding agent:        ./manage.sh start-coding-agent claude${ws_flag}  (or: opencode|vscode|codex)"
+}
+
+# Bring up a single agentic instance (always with MCP + Serena).
+#
+#   --ws N       target instance (non-negative integer). Default: 0 (ws0).
+#   --sync       re-seed the workspace from the live repo. Forbidden on main;
+#                ws1+ also sync implicitly the first time when their workspace
+#                directory does not exist yet.
+#   --serena-context CTX  passed to Serena (default: desktop-app).
+#   --git-user-name NAME  Git author/committer name to wire into the
+#                container's global git config (so commits made inside the
+#                devenv carry a real identity). Defaults to the host's
+#                effective `git config user.name` when omitted (resolved at
+#                the current working directory, so a per-repo local override
+#                in <repo>/.git/config takes precedence over ~/.gitconfig).
+#   --git-user-email EMAIL  matching email; defaults to the host's effective
+#                `git config user.email` (same local-over-global precedence).
+#
+# ws0 is the worker-bearer and must be running whenever any ws1+ is up. When
+# starting ws1+, ws0 is brought up first automatically if it is not already
+# running. Errors out if the requested target itself is already running.
 function run-devenv-agentic {
+    local target="ws0"
+    local do_sync=false
     local serena_context="desktop-app"
-    local serena_external_port="14281"
-    local serena_dashboard_external_port="14282"
+    local git_user_name=""
+    local git_user_email=""
 
     while [[ $# -gt 0 ]]; do
         case "$1" in
+            --ws)
+                target="$(parse-ws-integer "$2")" || return 1; shift 2;;
+            --sync)
+                do_sync=true; shift;;
             --serena-context)
                 serena_context="$2"; shift 2;;
+            --git-user-name)
+                git_user_name="$2"; shift 2;;
+            --git-user-email)
+                git_user_email="$2"; shift 2;;
             *)
-                shift;;
+                echo "run-devenv-agentic: unknown argument '$1'" >&2
+                return 1;;
         esac
     done
 
-    if [[ ! $(docker ps -f "name=penpot-devenv-main" -q) ]]; then
-        SERENA_EXTERNAL_PORT="$serena_external_port" \
-        SERENA_DASHBOARD_EXTERNAL_PORT="$serena_dashboard_external_port" \
-        start-devenv
-        echo "Waiting for containers fully start (5s)..."
-        sleep 5;
+    if [[ "$target" == "ws0" && "$do_sync" == "true" ]]; then
+        echo "run-devenv-agentic: --sync is not allowed on main (ws0)." >&2
+        return 1
     fi
 
-    run-devenv-tmux \
-        -e SERENA_ENABLED=true \
-        -e SERENA_CONTEXT="$serena_context" \
-        -e PENPOT_FLAGS="${PENPOT_FLAGS} enable-mcp"
+    # Fall back to the host developer's effective git identity when the
+    # respective flag is not provided. Plain `git config user.X` (no --global)
+    # honours the local->global->system precedence, so a per-repo override in
+    # <repo>/.git/config takes precedence over ~/.gitconfig -- matching what
+    # `git commit` on the host would actually record. `|| true` swallows the
+    # non-zero exit for a missing entry; the empty result is propagated
+    # untouched and surfaces as a no-op inside the container (start-tmux.sh
+    # skips `git config --global` when the env var is empty).
+    if [[ -z "$git_user_name" ]]; then
+        git_user_name="$(git config user.name 2>/dev/null || true)"
+    fi
+    if [[ -z "$git_user_email" ]]; then
+        git_user_email="$(git config user.email 2>/dev/null || true)"
+    fi
+    if [[ -z "$git_user_name" || -z "$git_user_email" ]]; then
+        echo "[$target] warning: host git identity is incomplete (name='${git_user_name}', email='${git_user_email}')." >&2
+        echo "  Commits made inside the devenv will fail until you set it via --git-user-name / --git-user-email" >&2
+        echo "  or 'git config user.{name,email}' on the host." >&2
+    fi
+
+    if devenv-main-running "$target"; then
+        echo "run-devenv-agentic: instance '$target' is already running." >&2
+        return 1
+    fi
+
+    # Pre-flight: frontend/resources/public/js/config.js must exist in the
+    # live repo. The file is gitignored; ws0 reads it directly from $PWD and
+    # wsN gets a one-shot copy on its initial sync. Without it the frontend
+    # never sets the 'enable-mcp' flag, so the agent can't drive Penpot via
+    # MCP. Fail fast (before any side effects) so the developer can fix it
+    # without leaving infra / containers half-started behind.
+    local cfg="frontend/resources/public/js/config.js"
+    if [[ ! -f "$PWD/$cfg" ]]; then
+        echo "$cfg is missing in the live repo." >&2
+        echo "Create it before running run-devenv-agentic -- the file is gitignored," >&2
+        echo "read directly from \$PWD on ws0 and copied into wsN only on its initial" >&2
+        echo "sync. Without it the Penpot frontend will not establish the MCP" >&2
+        echo "connection, so the agent cannot drive it. Minimal content:" >&2
+        echo "  var penpotFlags = \"enable-mcp\";" >&2
+        return 1
+    fi
+
+    pull-devenv-if-not-exists
+    ensure-devenv-network
+    ensure-infra-up
+
+    # ws0 invariant: must be up whenever any ws1+ runs. Bring it up first if a
+    # non-main instance is being requested and ws0 is not yet running.
+    if [[ "$target" != "ws0" ]] && ! devenv-main-running "ws0"; then
+        echo "[ws0] not running; starting it first (workers run only on ws0)."
+        echo "Starting ws0..."
+        write-instance-mcp-configs "ws0"
+        start-instance "ws0" "$serena_context" "$git_user_name" "$git_user_email"
+        print-instance-info "ws0"
+    fi
+
+    if [[ "$target" != "ws0" ]]; then
+        local workspace
+        workspace=$(workspace-path "$target")
+        if [[ ! -d "$workspace" ]]; then
+            echo "[$target] workspace at $workspace does not exist; performing initial sync."
+            do_sync=true
+        fi
+        if [[ "$do_sync" == "true" ]]; then
+            sync-workspace "$target"
+        fi
+    fi
+
+    echo "Starting $target..."
+    write-instance-mcp-configs "$target"
+    start-instance "$target" "$serena_context" "$git_user_name" "$git_user_email"
+    print-instance-info "$target"
 }
 
 function run-devenv-shell {
-    if [[ ! $(docker ps -f "name=penpot-devenv-main" -q) ]]; then
-        start-devenv
+    local instance="ws0"
+    local positional=()
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ws)
+                instance="$(parse-ws-integer "$2")" || return 1; shift 2;;
+            *)
+                positional+=("$1"); shift;;
+        esac
+    done
+
+    if ! devenv-main-running "$instance"; then
+        if [[ "$instance" == "ws0" ]]; then
+            start-devenv
+        else
+            echo "Instance '$instance' is not running." >&2
+            echo "Bring it up first with './manage.sh run-devenv-agentic --ws ${instance#ws}'." >&2
+            return 1
+        fi
     fi
+    # No positional args -> drop the user into a bash shell. Without this,
+    # `sudo -EH -u penpot` would be called with no command and just print its
+    # own usage.
+    if [[ ${#positional[@]} -eq 0 ]]; then
+        positional=(bash)
+    fi
+    local container
+    container=$(devenv-main-container "$instance")
     docker exec -ti \
+           -w /home/penpot/penpot \
            -e JAVA_OPTS="$JAVA_OPTS" \
            -e EXTERNAL_UID=$CURRENT_USER_ID \
-           penpot-devenv-main sudo -EH -u penpot $@
+           "$container" sudo -EH -u penpot "${positional[@]}"
+}
+
+function attach-devenv {
+    local instance="ws0"
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ws)
+                instance="$(parse-ws-integer "$2")" || return 1; shift 2;;
+            *)
+                echo "attach-devenv: unknown argument '$1'" >&2
+                return 1;;
+        esac
+    done
+
+    if ! devenv-main-running "$instance"; then
+        echo "Instance '$instance' is not running." >&2
+        echo "Start it first with './manage.sh run-devenv-agentic [--ws N]'." >&2
+        return 1
+    fi
+
+    local session="penpot"
+    local container
+    container=$(devenv-main-container "$instance")
+
+    if ! docker exec "$container" sudo -EH -u penpot tmux has-session -t "$session" 2>/dev/null; then
+        echo "No tmux session '$session' inside instance '$instance'." >&2
+        echo "The session may still be starting (the workspace's startup script runs the" >&2
+        echo "project setup before creating it) or it may have been closed. Wait and retry." >&2
+        return 1
+    fi
+
+    docker exec -ti "$container" sudo -EH -u penpot tmux attach -t "$session"
+}
+
+# Launch an AI coding agent against one parallel devenv workspace with the
+# right MCP config wired in. The generated config enhances rather than
+# replaces the developer's global client config; see .devenv/README.md for
+# the precedence rules and override paths.
+#
+# Target selection:
+#   no flag    → ws0 (the live repo at $PWD).
+#   --ws N     → wsN's workspace clone at ${PENPOT_WORKSPACES_DIR}/wsN
+#                (N is an integer; non-integer values are rejected).
+# Before launching, the function cd's into the resolved workspace and refuses
+# to start unless the target instance's 'main' container is up — the Penpot
+# and Serena MCP servers only exist while the devenv is running.
+#
+# Per-client launch behaviour:
+#   claude    exec'd with --mcp-config <workspace>/.devenv/mcp/claude-code.json
+#   opencode  exec'd with OPENCODE_CONFIG=<workspace>/.devenv/mcp/opencode.json
+#   vscode    'code' launched on the workspace; .vscode/mcp.json is
+#             auto-discovered by GitHub Copilot
+#   codex     'codex' exec'd from the workspace with our servers passed as
+#             `-c mcp_servers.<name>....` overrides (built fresh from the
+#             committed templates). Nothing is written to .codex/config.toml,
+#             so the developer's own Codex config is left untouched.
+#
+# Usage: ./manage.sh start-coding-agent <claude|opencode|vscode|codex> [--ws N] [...passthrough]
+function start-coding-agent {
+    local client="${1:-}"
+    [[ $# -gt 0 ]] && shift
+
+    case "$client" in
+        ""|-h|--help)
+            echo "Usage: $0 start-coding-agent <claude|opencode|vscode|codex> [--ws N] [...passthrough]" >&2
+            return 1
+            ;;
+        claude|opencode|vscode|codex)
+            ;;
+        *)
+            echo "start-coding-agent: unknown client '$client' (expected one of claude, opencode, vscode, codex)." >&2
+            return 1
+            ;;
+    esac
+
+    local instance="ws0"
+    if [[ $# -gt 0 && "$1" == "--ws" ]]; then
+        instance="$(parse-ws-integer "$2")" || return 1
+        shift 2
+    fi
+
+    # --ws is the default-elided flag: only emit it in suggestion strings for
+    # ws1+; ws0 is the default target so 'run-devenv-agentic' is the right hint.
+    local ws_flag=""
+    [[ "$instance" != "ws0" ]] && ws_flag=" --ws ${instance#ws}"
+
+    # Resolve the workspace directory for the target instance. ws0 binds
+    # the live repo; ws1+ are clones under PENPOT_WORKSPACES_DIR.
+    local workspace
+    if [[ "$instance" == "ws0" ]]; then
+        workspace="$PWD"
+    else
+        workspace="$(workspace-path "$instance")"
+        if [[ ! -d "$workspace" ]]; then
+            echo "start-coding-agent: workspace for $instance not found at $workspace." >&2
+            echo "Bring '$instance' up first with './manage.sh run-devenv-agentic${ws_flag}'." >&2
+            return 1
+        fi
+    fi
+
+    # The MCP servers the agent talks to only exist while 'main' is up.
+    # Refuse rather than launch an agent that would error on every tool call.
+    if ! devenv-main-running "$instance"; then
+        echo "start-coding-agent: instance '$instance' is not running." >&2
+        echo "Start it first with './manage.sh run-devenv-agentic${ws_flag}'." >&2
+        return 1
+    fi
+
+    # Per-client binary + config path (relative to the workspace dir so the
+    # launch line in error messages and `exec` is short and stable). Codex has
+    # no generated config file -- its servers are injected as `-c` flags below
+    # -- so cfg_rel points at the committed template that those flags are built
+    # from (present on ws0 in the repo, synced into ws1+).
+    local bin cfg_rel
+    case "$client" in
+        claude)   bin="claude";   cfg_rel=".devenv/mcp/claude-code.json" ;;
+        opencode) bin="opencode"; cfg_rel=".devenv/mcp/opencode.json" ;;
+        vscode)   bin="code";     cfg_rel=".vscode/mcp.json" ;;
+        codex)    bin="codex";    cfg_rel=".devenv/templates/codex.toml" ;;
+    esac
+
+    if ! command -v "$bin" >/dev/null 2>&1; then
+        echo "start-coding-agent: '$bin' is not on PATH." >&2
+        echo "Install it first, then retry." >&2
+        return 1
+    fi
+
+    if [[ ! -f "$workspace/$cfg_rel" ]]; then
+        echo "start-coding-agent: $workspace/$cfg_rel not found." >&2
+        echo "Bring '$instance' up with './manage.sh run-devenv-agentic${ws_flag}'," >&2
+        echo "which sets up the per-workspace MCP config." >&2
+        return 1
+    fi
+
+    cd "$workspace" || return 1
+    case "$client" in
+        claude)
+            exec claude --mcp-config "$cfg_rel" "$@"
+            ;;
+        opencode)
+            OPENCODE_CONFIG="$cfg_rel" exec opencode "$@"
+            ;;
+        vscode)
+            exec code "$workspace" "$@"
+            ;;
+        codex)
+            # Build our servers as `-c mcp_servers.<name>....` overrides from the
+            # committed templates (ports resolved from the instance number) and
+            # pass them on the command line. Nothing is written to disk, so the
+            # developer's project- or user-level .codex/config.toml is untouched.
+            PENPOT_MCP_PORT=$(instance-port "$instance" "$PENPOT_PORT_BASE_MCP")
+            SERENA_MCP_PORT=$(instance-port "$instance" "$PENPOT_PORT_BASE_SERENA")
+            export PENPOT_MCP_PORT SERENA_MCP_PORT
+            local -a codex_args=()
+            local _assignment
+            while IFS= read -r _assignment; do
+                [[ -n "$_assignment" ]] && codex_args+=(-c "$_assignment")
+            done < <(python3 .devenv/scripts/merge-mcp-config.py --format codex-args \
+                        .devenv/shared/codex.toml \
+                        .devenv/templates/codex.toml)
+            if [[ ${#codex_args[@]} -eq 0 ]]; then
+                echo "start-coding-agent: failed to build Codex MCP overrides from" >&2
+                echo "  .devenv/{shared,templates}/codex.toml." >&2
+                return 1
+            fi
+            exec codex "${codex_args[@]}" "$@"
+            ;;
+    esac
 }
 
 function run-devenv-isolated-shell {
-    docker volume create ${DEVENV_PNAME}_user_data;
+    local instance="ws0"
+    local positional=()
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --ws)
+                instance="$(parse-ws-integer "$2")" || return 1; shift 2;;
+            *)
+                positional+=("$1"); shift;;
+        esac
+    done
+
+    # Resolve the user_data volume and source tree for the target workspace.
+    # ws0 uses the baseline volume name from defaults.env; wsN follows the
+    # instance-env-overrides naming convention (penpotdev_<instance>_user_data)
+    # and bind-mounts the workspace clone instead of $PWD.
+    local user_data_volume source_path
+    if [[ "$instance" == "ws0" ]]; then
+        user_data_volume="$PENPOT_USER_DATA_VOLUME"
+        source_path="$PWD"
+    else
+        user_data_volume="penpotdev_${instance}_user_data"
+        source_path="$(workspace-path "$instance")"
+        if [[ ! -d "$source_path" ]]; then
+            echo "isolated-shell: workspace for $instance not found at $source_path." >&2
+            return 1
+        fi
+    fi
+
+    # No command -> drop into bash. Always cwd to the source-tree root;
+    # callers that need a subdir can `cd` inside the shell or pass
+    # `bash -c 'cd subdir && cmd'`.
+    if [[ ${#positional[@]} -eq 0 ]]; then
+        positional=(bash)
+    fi
+
+    docker volume create "$user_data_volume" >/dev/null
     docker run -ti --rm \
-           --mount source=${DEVENV_PNAME}_user_data,type=volume,target=/home/penpot/ \
-           --mount source=`pwd`,type=bind,target=/home/penpot/penpot \
+           --mount source="$user_data_volume",type=volume,target=/home/penpot/ \
+           --mount source="$source_path",type=bind,target=/home/penpot/penpot \
            -e EXTERNAL_UID=$CURRENT_USER_ID \
            -e BUILD_STORYBOOK=$BUILD_STORYBOOK \
            -e BUILD_WASM=$BUILD_WASM \
            -e SHADOWCLJS_EXTRA_PARAMS=$SHADOWCLJS_EXTRA_PARAMS \
            -e JAVA_OPTS="$JAVA_OPTS" \
-           -w /home/penpot/penpot/$1 \
-           $DEVENV_IMGNAME:latest sudo -EH -u penpot $@
+           -w /home/penpot/penpot \
+           "$DEVENV_IMGNAME:latest" sudo -EH -u penpot "${positional[@]}"
 }
 
 function build-imagemagick-docker-image {
@@ -217,9 +1137,9 @@ function build {
     local script=${2:-build}
 
     pull-devenv-if-not-exists;
-    docker volume create ${DEVENV_PNAME}_user_data;
+    docker volume create ${PENPOT_USER_DATA_VOLUME};
     docker run -t --rm \
-           --mount source=${DEVENV_PNAME}_user_data,type=volume,target=/home/penpot/ \
+           --mount source=${PENPOT_USER_DATA_VOLUME},type=volume,target=/home/penpot/ \
            --mount source=`pwd`,type=bind,target=/home/penpot/penpot \
            -e EXTERNAL_UID=$CURRENT_USER_ID \
            -e BUILD_STORYBOOK=$BUILD_STORYBOOK \
@@ -393,21 +1313,68 @@ function build-storybook-docker-image {
 function usage {
     echo "PENPOT build & release manager"
     echo "USAGE: $0 OPTION"
-    echo "Options:"
-    echo "- pull-devenv                      Pulls docker development oriented image"
-    echo "- build-devenv                     Build docker development oriented image"
-    echo "- build-devenv --local             Build a local docker development oriented image"
-    echo "- create-devenv                    Create the development oriented docker compose service."
-    echo "- start-devenv                     Start the development oriented docker compose service."
-    echo "- stop-devenv                      Stops the development oriented docker compose service."
-    echo "- drop-devenv                      Remove the development oriented docker compose containers, volumes and clean images."
-    echo "- run-devenv                       Attaches to the running devenv container and starts development environment"
+    echo ""
+    echo "Development environment (devenv)"
+    echo "--------------------------------"
+    echo "The devenv runs Penpot in a Docker container and supports parallel"
+    echo "'workspaces': ws0 (the live repo at \$PWD) and optional wsN (N >= 1, sibling"
+    echo "clones). Use --ws N to target a specific workspace; the default is 0."
+    echo "Full guide: docs/technical-guide/developer/{devenv,agentic-devenv}.md."
+    echo ""
+    echo "Image lifecycle"
+    echo "- pull-devenv                      Pull the devenv docker image from the registry."
+    echo "- build-devenv [--local]           Build the devenv docker image (--local skips the registry push)."
+    echo ""
+    echo "Bring a devenv up / down"
+    echo "- run-devenv-agentic               Bring one workspace up with AI-agent tooling enabled (MCP + Serena),"
+    echo "                                   start its tmux session in the background, regenerate the per-workspace"
+    echo "                                   MCP configs, and print the workspace's URLs. Errors out if the target"
+    echo "                                   is already running."
+    echo "                                   Options:"
+    echo "                                     --ws N                target workspace (default: 0). N >= 1 auto-starts"
+    echo "                                                           ws0 first if it is not already up."
+    echo "                                     --sync                re-seed the wsN clone from the live repo before"
+    echo "                                                           starting (forbidden on ws0; implicit on first"
+    echo "                                                           start of a wsN with no on-disk workspace yet)."
+    echo "                                     --serena-context CTX  passed to Serena (default: desktop-app)."
+    echo "                                     --git-user-name NAME / --git-user-email EMAIL"
+    echo "                                                           identity wired into the container's git config"
+    echo "                                                           (default: host's effective 'git config user.X',"
+    echo "                                                           honouring per-repo local overrides; see"
+    echo "                                                           devenv.md > 'Git identity inside the container')."
+    echo "- start-devenv                     Bring ws0 + shared infra up in the background (no tmux, no MCP/Serena)."
+    echo "- create-devenv                    Create ws0 + shared-infra compose services without starting them."
+    echo "- stop-devenv                      Stop one or more workspaces. Shared infra stops with the last one."
+    echo "                                   Options: --ws N (stop wsN, N >= 1) | (no flag) (stop ws0 + infra;"
+    echo "                                            refused if any wsN is still running) | --all (stop every wsN"
+    echo "                                            highest first, then ws0 + infra)."
+    echo "- drop-devenv                      Same CLI and invariants as stop-devenv (see above), plus removal of"
+    echo "                                   the shared devenv image on full teardowns (no flag, --ws 0, or --all)."
+    echo "                                   Refused if any wsN (N >= 1) is still running. A single --ws N (N >= 1)"
+    echo "                                   keeps the image since other workspaces still need it."
+    echo "- log-devenv                       Tail a workspace's compose logs."
+    echo "                                   Options: --ws N (default: 0)."
+    echo ""
+    echo "Work inside a running devenv"
+    echo "- attach-devenv                    Attach to the tmux session inside a running workspace."
+    echo "                                   Options: --ws N (default: 0)."
+    echo "- start-coding-agent <client>      Launch an AI coding agent against one workspace with the right MCP"
+    echo "                                   config wired in. cd's into the workspace, refuses to launch if the"
+    echo "                                   instance is not running, and forwards extra args to the client."
+    echo "                                   client: claude | opencode | vscode | codex"
+    echo "                                   Options: --ws N (default: 0). See agentic-devenv.md and"
+    echo "                                   .devenv/README.md for per-client setup and override paths."
+    echo "- run-devenv-shell                 Open a bash shell inside the workspace's running devenv container"
+    echo "                                   ('docker exec' into the live 'main' container alongside the tmux"
+    echo "                                   session). Requires the workspace to be up."
+    echo "                                   Options: --ws N (default: 0)."
+    echo "- run-devenv                       Start ws0 if needed and attach to its tmux session interactively."
     echo "                                   Optional -e flags are forwarded to 'docker exec' (e.g. -e MY_VAR=value)."
-    echo "- run-devenv-agentic               Like run-devenv but with additional processes for agentic development enabled."
-    echo "                                   Options: --serena-context CONTEXT (default: desktop-app)"
-    echo "- run-devenv-shell                 Attaches to the running devenv container and starts a bash shell."
-    echo "- isolated-shell                   Starts a bash shell in a new devenv container."
-    echo "- log-devenv                       Show logs of the running devenv docker compose service."
+    echo "- isolated-shell                   Spawn a fresh, ephemeral devenv container ('docker run', not 'docker exec')"
+    echo "                                   with the workspace's source tree and build-cache volume mounted. Use this"
+    echo "                                   for ad-hoc work that should not touch the running devenv (e.g. manual"
+    echo "                                   builds); the workspace does not need to be running."
+    echo "                                   Options: --ws N (default: 0)."
     echo ""
     echo "- build-bundle                     Build all bundles (frontend, backend, exporter, storybook and mcp)."
     echo "- build-frontend-bundle            Build frontend bundle"
@@ -455,6 +1422,12 @@ case $1 in
     run-devenv-agentic)
         run-devenv-agentic ${@:2}
         ;;
+    attach-devenv)
+        attach-devenv ${@:2}
+        ;;
+    start-coding-agent)
+        start-coding-agent "${@:2}"
+        ;;
     run-devenv-shell)
         run-devenv-shell ${@:2}
         ;;