From 71ba310b0d9afce993d884dae4ee4f5de72e861d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Yuniel=20Acosta=20P=C3=A9rez?=
 <33158051+yacosta738@users.noreply.github.com>
Date: Wed, 11 Mar 2026 08:32:58 +0100
Subject: [PATCH] feat(web): root docs locale and portless dev flow

---
 clients/agent-runtime/CONTRIBUTING.md         |  4 +-
 .../firmware/corvus-esp32-ui/README.md        |  2 +-
 clients/web/README.md                         | 18 +++-
 clients/web/apps/chat/README.md               |  4 +-
 clients/web/apps/chat/package.json            |  5 +-
 clients/web/apps/dashboard/README.md          |  4 +-
 clients/web/apps/dashboard/package.json       |  5 +-
 clients/web/apps/docs/README.md               |  6 ++
 clients/web/apps/docs/astro.config.mjs        | 15 +++-
 clients/web/apps/docs/package.json            |  7 +-
 .../docs/src/content/docs/{en => }/404.mdx    |  0
 .../clients/agent-runtime/architecture.md     |  0
 .../{en => }/clients/agent-runtime/ci-map.md  |  0
 .../{en => }/clients/agent-runtime/index.mdx  |  0
 .../clients/agent-runtime/pr-workflow.md      |  0
 .../src/content/docs/es/guides/structure.md   |  4 +-
 .../docs/{en => }/guides/architecture.md      |  0
 .../{en => }/guides/architecture/overview.md  |  0
 .../docs/{en => }/guides/cli-reference.md     |  0
 .../docs/{en => }/guides/configuration.md     |  0
 .../docs/{en => }/guides/customization.md     |  0
 .../docs/{en => }/guides/development.md       |  0
 .../content/docs/{en => }/guides/features.md  |  0
 .../docs/{en => }/guides/getting-started.md   |  0
 .../content/docs/{en => }/guides/gpg-setup.md |  0
 .../guides/hardware-peripherals-design.md     |  0
 .../content/docs/{en => }/guides/release.md   |  0
 .../content/docs/{en => }/guides/structure.md |  4 +-
 .../content/docs/{en => }/guides/surrealdb.md |  0
 .../docs/src/content/docs/{en => }/index.mdx  |  0
 .../docs/{en => }/intro/introduction.mdx      |  2 +-
 .../apps/docs/src/pages/en/[...slug].astro    |  7 ++
 clients/web/apps/docs/src/pages/index.astro   |  8 --
 clients/web/apps/marketing/README.md          |  8 +-
 clients/web/apps/marketing/astro.config.mjs   | 12 ++-
 clients/web/apps/marketing/package.json       |  7 +-
 clients/web/apps/marketing/public/install     | 85 ++++++++++++++++---
 .../web/apps/marketing/src/pages/index.astro  |  5 +-
 clients/web/package.json                      |  5 +-
 clients/web/pnpm-lock.yaml                    | 25 ++++++
 clients/web/pnpm-workspace.yaml               |  1 +
 41 files changed, 188 insertions(+), 55 deletions(-)
 mode change 100755 => 100644 clients/agent-runtime/CONTRIBUTING.md
 mode change 100755 => 100644 clients/agent-runtime/firmware/corvus-esp32-ui/README.md
 rename clients/web/apps/docs/src/content/docs/{en => }/404.mdx (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/clients/agent-runtime/architecture.md (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/clients/agent-runtime/ci-map.md (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/clients/agent-runtime/index.mdx (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/clients/agent-runtime/pr-workflow.md (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/guides/architecture.md (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/guides/architecture/overview.md (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/guides/cli-reference.md (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/guides/configuration.md (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/guides/customization.md (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/guides/development.md (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/guides/features.md (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/guides/getting-started.md (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/guides/gpg-setup.md (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/guides/hardware-peripherals-design.md (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/guides/release.md (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/guides/structure.md (95%)
 rename clients/web/apps/docs/src/content/docs/{en => }/guides/surrealdb.md (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/index.mdx (100%)
 rename clients/web/apps/docs/src/content/docs/{en => }/intro/introduction.mdx (98%)
 create mode 100644 clients/web/apps/docs/src/pages/en/[...slug].astro
 delete mode 100644 clients/web/apps/docs/src/pages/index.astro

diff --git a/clients/agent-runtime/CONTRIBUTING.md b/clients/agent-runtime/CONTRIBUTING.md
old mode 100755
new mode 100644
index b3879ce38..215354baf
--- a/clients/agent-runtime/CONTRIBUTING.md
+++ b/clients/agent-runtime/CONTRIBUTING.md
@@ -47,8 +47,8 @@ When PR traffic is high (especially with AI-assisted contributions), these rules
 - **Explicit rollback**: every PR must include a fast rollback path.
 - **Security-first review**: changes in `src/security/`, runtime, and CI need stricter validation.
 
-Full maintainer workflow: see [`../web/apps/docs/src/content/docs/en/clients/agent-runtime/pr-workflow.md`](../web/apps/docs/src/content/docs/en/clients/agent-runtime/pr-workflow.md).
-CI workflow ownership and triage map: see [`../web/apps/docs/src/content/docs/en/clients/agent-runtime/ci-map.md`](../web/apps/docs/src/content/docs/en/clients/agent-runtime/ci-map.md).
+Full maintainer workflow: see [`../web/apps/docs/src/content/docs/clients/agent-runtime/pr-workflow.md`](../web/apps/docs/src/content/docs/clients/agent-runtime/pr-workflow.md).
+CI workflow ownership and triage map: see [`../web/apps/docs/src/content/docs/clients/agent-runtime/ci-map.md`](../web/apps/docs/src/content/docs/clients/agent-runtime/ci-map.md).
 
 ## Agent Collaboration Guidance
 
diff --git a/clients/agent-runtime/firmware/corvus-esp32-ui/README.md b/clients/agent-runtime/firmware/corvus-esp32-ui/README.md
old mode 100755
new mode 100644
index be2de327f..71504302e
--- a/clients/agent-runtime/firmware/corvus-esp32-ui/README.md
+++ b/clients/agent-runtime/firmware/corvus-esp32-ui/README.md
@@ -103,4 +103,4 @@ MIT - See root `LICENSE`
 
 - [Slint ESP32 Documentation](https://slint.dev/esp32)
 - [ESP-IDF Rust Book](https://docs.espressif.com/projects/rust/book/)
-- [Corvus Hardware Design](../../../web/apps/docs/src/content/docs/en/guides/hardware-peripherals-design.md)
+- [Corvus Hardware Design](../../../web/apps/docs/src/content/docs/guides/hardware-peripherals-design.md)
diff --git a/clients/web/README.md b/clients/web/README.md
index 8d1e9361a..220f34388 100644
--- a/clients/web/README.md
+++ b/clients/web/README.md
@@ -23,24 +23,29 @@ clients/web/
 ### docs
 
 - Framework: Astro + Starlight
-- Default port: 4321
+- Portless dev URL: `http://docs.localhost:1355`
+- Legacy dev port (PORTLESS=0): 4321
 
 ### marketing
 
 - Framework: Astro
-- URL configurable with `MARKETING_URL` (dev default: `http://localhost:9988`)
+- Portless dev URL: `http://marketing.localhost:1355`
+- Legacy dev port (PORTLESS=0): 9988
+- URL configurable with `MARKETING_URL` (dev fallback: `http://localhost:9988`)
 - Includes public install script at `/install`
 
 ### chat
 
 - Framework: Vue 3 + Vite + Tailwind + shadcn-vue style components
-- Default port: 4323
+- Portless dev URL: `http://chat.localhost:1355`
+- Legacy dev port (PORTLESS=0): 4323
 - ChatGPT-style conversational interface
 
 ### dashboard
 
 - Framework: Vue 3 + Vite
-- Default port: 4324
+- Portless dev URL: `http://dashboard.localhost:1355`
+- Legacy dev port (PORTLESS=0): 4324
 - Secure admin panel for `GET/PUT /web/admin/config`
 - `GET/PUT /web/admin/config` require auth when pairing is enabled (`[gateway] require_pairing = true` in `clients/agent-runtime/config.toml`)
 - Supported mechanism: bearer token (`Authorization: Bearer <token>`)
@@ -53,6 +58,8 @@ Minimum requirements:
 
 - Node.js 22.0.0+
 - pnpm 10.30+
+- portless (local devDependency; installed via `pnpm install`)
+- One-off usage without install: `pnpm dlx portless` or `npx portless`
 
 ```bash
 # Install workspace dependencies
@@ -76,6 +83,9 @@ pnpm dev:marketing
 pnpm dev:chat
 pnpm dev:dashboard
 
+# Run without portless (uses legacy localhost ports)
+PORTLESS=0 pnpm dev:chat
+
 # Compatibility (legacy alias)
 pnpm dev:landing
 
diff --git a/clients/web/apps/chat/README.md b/clients/web/apps/chat/README.md
index 37a1cbec6..a59cd397d 100644
--- a/clients/web/apps/chat/README.md
+++ b/clients/web/apps/chat/README.md
@@ -20,4 +20,6 @@ pnpm install
 pnpm dev:chat
 ```
 
-Chat runs on <http://localhost:4323>.
+Chat runs on <http://chat.localhost:1355> via portless.
+
+Use `PORTLESS=0 pnpm dev:chat` to run on <http://localhost:4323>.
diff --git a/clients/web/apps/chat/package.json b/clients/web/apps/chat/package.json
index 806a1c390..ddde1c160 100644
--- a/clients/web/apps/chat/package.json
+++ b/clients/web/apps/chat/package.json
@@ -8,9 +8,9 @@
     "node": ">=22.0.0"
   },
   "scripts": {
-    "dev": "vite --config vite.config.ts --port 4323",
+    "dev": "portless run --name chat vite --config vite.config.ts",
     "build": "vue-tsc -b && vite build --config vite.config.ts",
-    "preview": "vite preview --config vite.config.ts --port 4323",
+    "preview": "portless run --name chat vite preview --config vite.config.ts",
     "format": "biome format --write src package.json components.json tsconfig*.json vite.config.ts index.html",
     "check": "biome check src package.json components.json tsconfig*.json vite.config.ts index.html",
     "test": "vitest --config vite.config.ts --run",
@@ -37,6 +37,7 @@
     "@vue/tsconfig": "catalog:",
     "happy-dom": "catalog:",
     "postcss": "catalog:",
+    "portless": "catalog:",
     "tailwindcss": "catalog:",
     "typescript": "catalog:",
     "vite": "catalog:",
diff --git a/clients/web/apps/dashboard/README.md b/clients/web/apps/dashboard/README.md
index 545666029..e378aa11f 100644
--- a/clients/web/apps/dashboard/README.md
+++ b/clients/web/apps/dashboard/README.md
@@ -16,7 +16,9 @@ pnpm install
 pnpm dev:dashboard
 ```
 
-Dashboard corre en <http://localhost:4324>.
+Dashboard corre en <http://dashboard.localhost:1355> vía portless.
+
+Usa `PORTLESS=0 pnpm dev:dashboard` para correr en <http://localhost:4324>.
 
 ## Docker (local-first)
 
diff --git a/clients/web/apps/dashboard/package.json b/clients/web/apps/dashboard/package.json
index 07492a819..84a06051e 100644
--- a/clients/web/apps/dashboard/package.json
+++ b/clients/web/apps/dashboard/package.json
@@ -8,9 +8,9 @@
     "node": ">=22.0.0"
   },
   "scripts": {
-    "dev": "vite --port 4324",
+    "dev": "portless run --name dashboard vite",
     "build": "vue-tsc -b && vite build",
-    "preview": "vite preview --port 4324",
+    "preview": "portless run --name dashboard vite preview",
     "format": "biome format --write src package.json components.json tsconfig*.json vite.config.ts index.html",
     "check": "biome check src package.json components.json tsconfig*.json vite.config.ts index.html",
     "test": "vitest --run --environment happy-dom --exclude e2e/**",
@@ -38,6 +38,7 @@
     "@vue/tsconfig": "catalog:",
     "happy-dom": "catalog:",
     "postcss": "catalog:",
+    "portless": "catalog:",
     "tailwindcss": "catalog:",
     "typescript": "catalog:",
     "vite": "catalog:",
diff --git a/clients/web/apps/docs/README.md b/clients/web/apps/docs/README.md
index 00b5aa35b..6843b6876 100644
--- a/clients/web/apps/docs/README.md
+++ b/clients/web/apps/docs/README.md
@@ -14,6 +14,12 @@ pnpm install
 # Start dev server
 pnpm run dev
 
+# Portless URL (default)
+# http://docs.localhost:1355
+
+# Run without portless (legacy localhost port)
+PORTLESS=0 pnpm run dev
+
 # Build static site
 pnpm run build
 
diff --git a/clients/web/apps/docs/astro.config.mjs b/clients/web/apps/docs/astro.config.mjs
index 69cdb704d..f2fd80353 100644
--- a/clients/web/apps/docs/astro.config.mjs
+++ b/clients/web/apps/docs/astro.config.mjs
@@ -9,8 +9,11 @@ const DEFAULT_PROD_URL = "https://docs.profiletailors.com";
 
 const mode = process.env.NODE_ENV || "production";
 const env = loadEnv(mode, process.cwd(), "");
+const portlessUrl =
+  mode === "production" ? undefined : process.env.PORTLESS_URL ?? env.PORTLESS_URL;
+const runtimeEnv = portlessUrl ? { ...env, DOCS_URL: portlessUrl } : env;
 const docsUrl = resolveSiteUrl({
-  env,
+  env: runtimeEnv,
   primaryKey: "DOCS_URL",
   localDefault: DEFAULT_DEV_URL,
   productionDefault: DEFAULT_PROD_URL,
@@ -22,7 +25,11 @@ const docsUrl = resolveSiteUrl({
   },
   isProdLike: mode === "production",
 });
-const resolvedPort = getPortFromUrl(docsUrl, PORTS.DOCS);
+const portCandidate = process.env.PORT ?? env.PORT;
+const parsedPort = Number.parseInt(portCandidate ?? "", 10);
+const resolvedPort = Number.isFinite(parsedPort)
+  ? parsedPort
+  : getPortFromUrl(docsUrl, PORTS.DOCS);
 
 export default defineConfig({
   site: docsUrl,
@@ -42,9 +49,9 @@ export default defineConfig({
         light: "./public/favicon.svg",
         dark: "./public/favicon-light.svg",
       },
-      defaultLocale: "en",
+      defaultLocale: "root",
       locales: {
-        en: { label: "English", lang: "en" },
+        root: { label: "English", lang: "en" },
         es: { label: "Español", lang: "es" },
       },
       plugins: [viewTransitions()],
diff --git a/clients/web/apps/docs/package.json b/clients/web/apps/docs/package.json
index f3106c8f0..00e7e83fd 100644
--- a/clients/web/apps/docs/package.json
+++ b/clients/web/apps/docs/package.json
@@ -3,10 +3,10 @@
   "type": "module",
   "version": "0.4.0",
   "scripts": {
-    "dev": "astro dev",
-    "start": "astro dev",
+    "dev": "portless run --name docs astro dev",
+    "start": "portless run --name docs astro dev",
     "build": "astro build",
-    "preview": "astro preview",
+    "preview": "portless run --name docs astro preview",
     "astro": "astro",
     "format": "biome format --write src astro.config.mjs package.json tsconfig.json",
     "lint": "biome lint src astro.config.mjs",
@@ -21,6 +21,7 @@
   "devDependencies": {
     "@astrojs/check": "catalog:",
     "astro-vtbot": "catalog:",
+    "portless": "catalog:",
     "typescript": "catalog:",
     "vite": "catalog:"
   }
diff --git a/clients/web/apps/docs/src/content/docs/en/404.mdx b/clients/web/apps/docs/src/content/docs/404.mdx
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/404.mdx
rename to clients/web/apps/docs/src/content/docs/404.mdx
diff --git a/clients/web/apps/docs/src/content/docs/en/clients/agent-runtime/architecture.md b/clients/web/apps/docs/src/content/docs/clients/agent-runtime/architecture.md
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/clients/agent-runtime/architecture.md
rename to clients/web/apps/docs/src/content/docs/clients/agent-runtime/architecture.md
diff --git a/clients/web/apps/docs/src/content/docs/en/clients/agent-runtime/ci-map.md b/clients/web/apps/docs/src/content/docs/clients/agent-runtime/ci-map.md
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/clients/agent-runtime/ci-map.md
rename to clients/web/apps/docs/src/content/docs/clients/agent-runtime/ci-map.md
diff --git a/clients/web/apps/docs/src/content/docs/en/clients/agent-runtime/index.mdx b/clients/web/apps/docs/src/content/docs/clients/agent-runtime/index.mdx
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/clients/agent-runtime/index.mdx
rename to clients/web/apps/docs/src/content/docs/clients/agent-runtime/index.mdx
diff --git a/clients/web/apps/docs/src/content/docs/en/clients/agent-runtime/pr-workflow.md b/clients/web/apps/docs/src/content/docs/clients/agent-runtime/pr-workflow.md
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/clients/agent-runtime/pr-workflow.md
rename to clients/web/apps/docs/src/content/docs/clients/agent-runtime/pr-workflow.md
diff --git a/clients/web/apps/docs/src/content/docs/es/guides/structure.md b/clients/web/apps/docs/src/content/docs/es/guides/structure.md
index b8b1651b9..216b438ca 100644
--- a/clients/web/apps/docs/src/content/docs/es/guides/structure.md
+++ b/clients/web/apps/docs/src/content/docs/es/guides/structure.md
@@ -45,7 +45,7 @@ Contiene todas las aplicaciones cliente que consumen los módulos compartidos:
 
 ## El Directorio `docs`
 
-- **`docs/es/`**: Documentación en español.
+- **`docs/`**: Documentación en inglés (locale raíz).
   - `index.mdx`: Página de inicio.
   - `guides/`: Guías detalladas del proyecto.
-- **`docs/en/`**: Documentación en inglés (si aplica).
+- **`docs/es/`**: Documentación en español.
diff --git a/clients/web/apps/docs/src/content/docs/en/guides/architecture.md b/clients/web/apps/docs/src/content/docs/guides/architecture.md
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/guides/architecture.md
rename to clients/web/apps/docs/src/content/docs/guides/architecture.md
diff --git a/clients/web/apps/docs/src/content/docs/en/guides/architecture/overview.md b/clients/web/apps/docs/src/content/docs/guides/architecture/overview.md
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/guides/architecture/overview.md
rename to clients/web/apps/docs/src/content/docs/guides/architecture/overview.md
diff --git a/clients/web/apps/docs/src/content/docs/en/guides/cli-reference.md b/clients/web/apps/docs/src/content/docs/guides/cli-reference.md
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/guides/cli-reference.md
rename to clients/web/apps/docs/src/content/docs/guides/cli-reference.md
diff --git a/clients/web/apps/docs/src/content/docs/en/guides/configuration.md b/clients/web/apps/docs/src/content/docs/guides/configuration.md
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/guides/configuration.md
rename to clients/web/apps/docs/src/content/docs/guides/configuration.md
diff --git a/clients/web/apps/docs/src/content/docs/en/guides/customization.md b/clients/web/apps/docs/src/content/docs/guides/customization.md
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/guides/customization.md
rename to clients/web/apps/docs/src/content/docs/guides/customization.md
diff --git a/clients/web/apps/docs/src/content/docs/en/guides/development.md b/clients/web/apps/docs/src/content/docs/guides/development.md
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/guides/development.md
rename to clients/web/apps/docs/src/content/docs/guides/development.md
diff --git a/clients/web/apps/docs/src/content/docs/en/guides/features.md b/clients/web/apps/docs/src/content/docs/guides/features.md
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/guides/features.md
rename to clients/web/apps/docs/src/content/docs/guides/features.md
diff --git a/clients/web/apps/docs/src/content/docs/en/guides/getting-started.md b/clients/web/apps/docs/src/content/docs/guides/getting-started.md
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/guides/getting-started.md
rename to clients/web/apps/docs/src/content/docs/guides/getting-started.md
diff --git a/clients/web/apps/docs/src/content/docs/en/guides/gpg-setup.md b/clients/web/apps/docs/src/content/docs/guides/gpg-setup.md
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/guides/gpg-setup.md
rename to clients/web/apps/docs/src/content/docs/guides/gpg-setup.md
diff --git a/clients/web/apps/docs/src/content/docs/en/guides/hardware-peripherals-design.md b/clients/web/apps/docs/src/content/docs/guides/hardware-peripherals-design.md
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/guides/hardware-peripherals-design.md
rename to clients/web/apps/docs/src/content/docs/guides/hardware-peripherals-design.md
diff --git a/clients/web/apps/docs/src/content/docs/en/guides/release.md b/clients/web/apps/docs/src/content/docs/guides/release.md
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/guides/release.md
rename to clients/web/apps/docs/src/content/docs/guides/release.md
diff --git a/clients/web/apps/docs/src/content/docs/en/guides/structure.md b/clients/web/apps/docs/src/content/docs/guides/structure.md
similarity index 95%
rename from clients/web/apps/docs/src/content/docs/en/guides/structure.md
rename to clients/web/apps/docs/src/content/docs/guides/structure.md
index 60feb8201..2c43abbb8 100644
--- a/clients/web/apps/docs/src/content/docs/en/guides/structure.md
+++ b/clients/web/apps/docs/src/content/docs/guides/structure.md
@@ -42,7 +42,7 @@ Contains all client applications that consume the shared modules:
 
 ## Documentation
 
-- **`clients/web/apps/docs/src/content/docs/es/`**: Documentation in Spanish.
+- **`clients/web/apps/docs/src/content/docs/`**: Documentation in English (root locale).
   - `index.mdx`: Home page.
   - `guides/`: Detailed project guides.
-- **`clients/web/apps/docs/src/content/docs/en/`**: Documentation in English.
+- **`clients/web/apps/docs/src/content/docs/es/`**: Documentation in Spanish.
diff --git a/clients/web/apps/docs/src/content/docs/en/guides/surrealdb.md b/clients/web/apps/docs/src/content/docs/guides/surrealdb.md
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/guides/surrealdb.md
rename to clients/web/apps/docs/src/content/docs/guides/surrealdb.md
diff --git a/clients/web/apps/docs/src/content/docs/en/index.mdx b/clients/web/apps/docs/src/content/docs/index.mdx
similarity index 100%
rename from clients/web/apps/docs/src/content/docs/en/index.mdx
rename to clients/web/apps/docs/src/content/docs/index.mdx
diff --git a/clients/web/apps/docs/src/content/docs/en/intro/introduction.mdx b/clients/web/apps/docs/src/content/docs/intro/introduction.mdx
similarity index 98%
rename from clients/web/apps/docs/src/content/docs/en/intro/introduction.mdx
rename to clients/web/apps/docs/src/content/docs/intro/introduction.mdx
index e5f5347a2..e432e02cc 100644
--- a/clients/web/apps/docs/src/content/docs/en/intro/introduction.mdx
+++ b/clients/web/apps/docs/src/content/docs/intro/introduction.mdx
@@ -7,7 +7,7 @@ description: Welcome to the Corvus Agent Platform documentation.
 
 **Corvus** is a highly extensible, multi-interface agentic platform designed to bridge the gap between AI autonomy and human supervision. Built with a robust **Kotlin Multiplatform** foundation and powered by a high-performance **Rust** runtime, Corvus provides a secure, sandboxed environment for AI agents to perform complex, multi-step tasks.
 
-![Corvus Architecture](../../../../assets/corvus.png)
+![Corvus Architecture](../../../assets/corvus.png)
 
 ## ✨ Features
 
diff --git a/clients/web/apps/docs/src/pages/en/[...slug].astro b/clients/web/apps/docs/src/pages/en/[...slug].astro
new file mode 100644
index 000000000..053ed8a9e
--- /dev/null
+++ b/clients/web/apps/docs/src/pages/en/[...slug].astro
@@ -0,0 +1,7 @@
+---
+const { slug } = Astro.params;
+const baseUrl = import.meta.env.BASE_URL.endsWith("/")
+  ? import.meta.env.BASE_URL.slice(0, -1)
+  : import.meta.env.BASE_URL;
+Astro.redirect(`${baseUrl}${slug ? `/${slug}` : "/"}`);
+---
diff --git a/clients/web/apps/docs/src/pages/index.astro b/clients/web/apps/docs/src/pages/index.astro
deleted file mode 100644
index 820effff0..000000000
--- a/clients/web/apps/docs/src/pages/index.astro
+++ /dev/null
@@ -1,8 +0,0 @@
----
-// This page handles the redirect from the base root to the default locale
-return Astro.redirect(
-  import.meta.env.BASE_URL.endsWith("/")
-    ? `${import.meta.env.BASE_URL}en/`
-    : `${import.meta.env.BASE_URL}/en/`
-);
----
diff --git a/clients/web/apps/marketing/README.md b/clients/web/apps/marketing/README.md
index 848576d0e..1672cc64b 100644
--- a/clients/web/apps/marketing/README.md
+++ b/clients/web/apps/marketing/README.md
@@ -23,11 +23,15 @@ pnpm build:marketing
 pnpm --filter @corvus/marketing run check
 ```
 
+Dev URL (portless): <http://marketing.localhost:1355>
+
+Sin portless: `PORTLESS=0 pnpm dev:marketing` (usa `http://localhost:9988`).
+
 ## Configuración de dominio y puerto
 
-- Dev default: `http://localhost:9988`
+- Dev default: `http://marketing.localhost:1355` (portless)
 - Prod default: `https://profiletailors.com`
-- El puerto de `dev/preview` se toma de `MARKETING_URL` si incluye puerto; si no, usa `9988`
+- El puerto de `dev/preview` se toma de `PORT` (portless) o de `MARKETING_URL` si incluye puerto; si no, usa `9988`
 
 Variable soportada:
 
diff --git a/clients/web/apps/marketing/astro.config.mjs b/clients/web/apps/marketing/astro.config.mjs
index b1e11323e..94124e670 100644
--- a/clients/web/apps/marketing/astro.config.mjs
+++ b/clients/web/apps/marketing/astro.config.mjs
@@ -9,11 +9,19 @@ const DEFAULT_PROD_URL = "https://profiletailors.com";
 const mode = process.env.NODE_ENV || "production";
 const env = loadEnv(mode, process.cwd(), "");
 
+const portlessUrl =
+  mode === "production"
+    ? ""
+    : resolvePublicUrl(process.env.PORTLESS_URL ?? env.PORTLESS_URL, "");
 const marketingUrl = resolvePublicUrl(
-  env.MARKETING_URL,
+  env.MARKETING_URL ?? (portlessUrl || undefined),
   mode === "production" ? DEFAULT_PROD_URL : DEFAULT_DEV_URL
 );
-const resolvedPort = getPortFromUrl(marketingUrl, PORTS.MARKETING);
+const portCandidate = process.env.PORT ?? env.PORT;
+const parsedPort = Number.parseInt(portCandidate ?? "", 10);
+const resolvedPort = Number.isFinite(parsedPort)
+  ? parsedPort
+  : getPortFromUrl(marketingUrl, PORTS.MARKETING);
 
 export default defineConfig({
   site: marketingUrl,
diff --git a/clients/web/apps/marketing/package.json b/clients/web/apps/marketing/package.json
index 85b1e2a88..5d862eedb 100644
--- a/clients/web/apps/marketing/package.json
+++ b/clients/web/apps/marketing/package.json
@@ -6,12 +6,12 @@
   "type": "module",
   "scripts": {
     "copy-install": "bash -c 'if [ -f ../../../../scripts/install.sh ]; then cp ../../../../scripts/install.sh public/install; else echo \"scripts/install.sh not found; skipping copy\"; fi'",
-    "dev": "astro dev",
+    "dev": "portless run --name marketing astro dev",
     "predev": "pnpm run copy-install",
-    "start": "astro dev",
+    "start": "portless run --name marketing astro dev",
     "build": "astro build",
     "prebuild": "pnpm run copy-install",
-    "preview": "astro preview",
+    "preview": "portless run --name marketing astro preview",
     "astro": "astro",
     "format": "biome format --write src public package.json astro.config.mjs tsconfig.json README.md",
     "check": "biome check src public package.json astro.config.mjs tsconfig.json README.md",
@@ -23,6 +23,7 @@
     "sharp": "catalog:"
   },
   "devDependencies": {
+    "portless": "catalog:",
     "typescript": "catalog:",
     "vite": "catalog:"
   }
diff --git a/clients/web/apps/marketing/public/install b/clients/web/apps/marketing/public/install
index 32150e3af..00ddedbac 100755
--- a/clients/web/apps/marketing/public/install
+++ b/clients/web/apps/marketing/public/install
@@ -26,6 +26,7 @@ APT_INDEX_UPDATED="0"
 ALREADY_INSTALLED="0"
 EXISTING_CMD_PATH=""
 EXISTING_INSTALL_DIR=""
+EXISTING_INSTALL_METHOD=""
 SKIP_ONBOARD_REASON=""
 
 OS_TYPE=""
@@ -48,6 +49,28 @@ detect_existing_install() {
     EXISTING_CMD_PATH="$(command -v corvus)"
     EXISTING_INSTALL_DIR="$(dirname "$EXISTING_CMD_PATH")"
     ALREADY_INSTALLED="1"
+    if [ -L "$EXISTING_CMD_PATH" ] || printf "%s" "$EXISTING_CMD_PATH" | grep -q "/node_modules/.bin/"; then
+      EXISTING_INSTALL_METHOD="package"
+    else
+      local first_line=""
+      first_line="$(head -n 1 "$EXISTING_CMD_PATH" 2>/dev/null || true)"
+      if printf "%s" "$first_line" | grep -qi "node"; then
+        EXISTING_INSTALL_METHOD="package"
+      fi
+    fi
+
+    if [ "$EXISTING_INSTALL_METHOD" = "package" ]; then
+      case "$EXISTING_CMD_PATH" in
+        *pnpm*) EXISTING_INSTALL_METHOD="pnpm" ;;
+        *yarn*) EXISTING_INSTALL_METHOD="yarn" ;;
+        *bun*) EXISTING_INSTALL_METHOD="bun" ;;
+        *npm*) EXISTING_INSTALL_METHOD="npm" ;;
+      esac
+    fi
+
+    if [ -z "$EXISTING_INSTALL_METHOD" ]; then
+      EXISTING_INSTALL_METHOD="binary"
+    fi
   fi
 
   if [ -f "$config_path" ]; then
@@ -555,7 +578,7 @@ resolve_install_dir() {
     return
   fi
 
-  if [ -n "$EXISTING_INSTALL_DIR" ]; then
+  if [ -n "$EXISTING_INSTALL_DIR" ] && [ "$EXISTING_INSTALL_METHOD" = "binary" ]; then
     printf "%s" "$EXISTING_INSTALL_DIR"
     return
   fi
@@ -775,7 +798,15 @@ install_via_package_manager() {
       ;;
     yarn)
       has_cmd yarn || die "yarn is not installed."
-      yarn global add "$CLI_PACKAGE"
+      local yarn_version=""
+      local yarn_major=""
+      yarn_version="$(yarn --version 2>/dev/null || true)"
+      yarn_major="${yarn_version%%.*}"
+      if [ -n "$yarn_version" ] && [ "$yarn_major" -ge 2 ] 2>/dev/null; then
+        yarn dlx "$CLI_PACKAGE"
+      else
+        yarn global add "$CLI_PACKAGE"
+      fi
       ;;
     bun)
       has_cmd bun || die "bun is not installed."
@@ -798,12 +829,25 @@ select_install_method() {
     return
   fi
 
-  if [ "$ALREADY_INSTALLED" = "1" ]; then
+  if [ "$ALREADY_INSTALLED" = "1" ] && [ "$EXISTING_INSTALL_METHOD" = "binary" ]; then
     INSTALL_METHOD="binary"
     print_info "Existing Corvus install detected at ${EXISTING_CMD_PATH}. Updating in place."
     return
   fi
 
+  if [ "$ALREADY_INSTALLED" = "1" ] && [ -n "$EXISTING_INSTALL_METHOD" ] && [ "$EXISTING_INSTALL_METHOD" != "binary" ]; then
+    case "$EXISTING_INSTALL_METHOD" in
+      pnpm|npm|yarn|bun)
+        INSTALL_METHOD="$EXISTING_INSTALL_METHOD"
+        print_info "Existing Corvus install detected at ${EXISTING_CMD_PATH}."
+        return
+        ;;
+      *)
+        print_info "Existing Corvus install detected at ${EXISTING_CMD_PATH}."
+        ;;
+    esac
+  fi
+
   candidates=("binary")
   has_cmd pnpm && candidates+=("pnpm")
   has_cmd npm && candidates+=("npm")
@@ -811,7 +855,18 @@ select_install_method() {
   has_cmd bun && candidates+=("bun")
 
   if ! is_interactive; then
-    INSTALL_METHOD="binary"
+    if [ "$ALREADY_INSTALLED" = "1" ] && [ -n "$EXISTING_INSTALL_METHOD" ] && [ "$EXISTING_INSTALL_METHOD" != "binary" ]; then
+      case "$EXISTING_INSTALL_METHOD" in
+        pnpm|npm|yarn|bun)
+          INSTALL_METHOD="$EXISTING_INSTALL_METHOD"
+          ;;
+        *)
+          INSTALL_METHOD="binary"
+          ;;
+      esac
+    else
+      INSTALL_METHOD="binary"
+    fi
     return
   fi
 
@@ -859,10 +914,10 @@ post_install_steps() {
   local resolved_cmd=""
   local resolved_version=""
 
-  if has_cmd corvus; then
-    resolved_cmd="$(command -v corvus)"
-  elif [ -n "$INSTALLED_BINARY_PATH" ] && [ -x "$INSTALLED_BINARY_PATH" ]; then
+  if [ -n "$INSTALLED_BINARY_PATH" ] && [ -x "$INSTALLED_BINARY_PATH" ]; then
     resolved_cmd="$INSTALLED_BINARY_PATH"
+  elif has_cmd corvus; then
+    resolved_cmd="$(command -v corvus)"
   fi
 
   if [ -z "$resolved_cmd" ]; then
@@ -871,7 +926,7 @@ post_install_steps() {
     return
   fi
 
-  resolved_version="$($resolved_cmd --version 2>/dev/null || echo 'installed')"
+  resolved_version="$("$resolved_cmd" --version 2>/dev/null || echo 'installed')"
   print_success "Corvus CLI available: ${resolved_version}"
 
   if [ "$SKIP_ONBOARD" = "1" ]; then
@@ -895,10 +950,10 @@ post_install_steps() {
 restart_daemon_if_available() {
   local resolved_cmd=""
 
-  if has_cmd corvus; then
-    resolved_cmd="$(command -v corvus)"
-  elif [ -n "$INSTALLED_BINARY_PATH" ] && [ -x "$INSTALLED_BINARY_PATH" ]; then
+  if [ -n "$INSTALLED_BINARY_PATH" ] && [ -x "$INSTALLED_BINARY_PATH" ]; then
     resolved_cmd="$INSTALLED_BINARY_PATH"
+  elif has_cmd corvus; then
+    resolved_cmd="$(command -v corvus)"
   fi
 
   if [ -z "$resolved_cmd" ]; then
@@ -908,9 +963,15 @@ restart_daemon_if_available() {
   if "$resolved_cmd" service status >/dev/null 2>&1; then
     print_info "Restarting Corvus service to apply updates..."
     if "$resolved_cmd" service restart >/dev/null 2>&1; then
-      print_success "Corvus service restarted"
+      if "$resolved_cmd" doctor >/dev/null 2>&1; then
+        print_success "Corvus service restarted"
+      else
+        print_warn "Corvus service restart completed, but health check failed"
+        return 1
+      fi
     else
       print_warn "Corvus service restart failed. Try: corvus service restart"
+      return 1
     fi
   else
     print_info "Corvus service not installed; skipping restart."
diff --git a/clients/web/apps/marketing/src/pages/index.astro b/clients/web/apps/marketing/src/pages/index.astro
index 32b91cef1..b5665a1d5 100644
--- a/clients/web/apps/marketing/src/pages/index.astro
+++ b/clients/web/apps/marketing/src/pages/index.astro
@@ -13,8 +13,11 @@ const mode = process.env.NODE_ENV || "production";
 const env = loadEnv(mode, process.cwd(), "");
 
 const isProdLike = mode === "production";
+const portlessUrl = isProdLike
+  ? ""
+  : resolvePublicUrl(process.env.PORTLESS_URL ?? env.PORTLESS_URL, "");
 const marketingBaseUrl = resolvePublicUrl(
-  env.MARKETING_URL,
+  env.MARKETING_URL ?? (portlessUrl || undefined),
   isProdLike ? DEFAULT_MARKETING_PROD_URL : DEFAULT_MARKETING_DEV_URL
 );
 const docsBaseUrl = resolvePublicUrl(
diff --git a/clients/web/package.json b/clients/web/package.json
index ff3edd64e..d9e21e214 100644
--- a/clients/web/package.json
+++ b/clients/web/package.json
@@ -12,7 +12,8 @@
     "build:landing": "pnpm run build:marketing",
     "build:chat": "pnpm --filter @corvus/chat run build",
     "build:dashboard": "pnpm --filter @corvus/dashboard run build",
-    "dev": "pnpm --filter @corvus/docs run dev",
+    "dev": "pnpm --parallel -r run dev",
+    "dev:docs": "pnpm --filter @corvus/docs run dev",
     "dev:marketing": "pnpm --filter @corvus/marketing run dev",
     "dev:landing": "pnpm run dev:marketing",
     "dev:chat": "pnpm --filter @corvus/chat run dev",
@@ -38,7 +39,7 @@
       "rollup": "^4.59.0"
     }
   },
-  "packageManager": "pnpm@10.31.0",
+  "packageManager": "pnpm@10.32.1",
   "engines": {
     "node": ">=22.12.0",
     "pnpm": ">=10.28.0"
diff --git a/clients/web/pnpm-lock.yaml b/clients/web/pnpm-lock.yaml
index 612cbe351..ad0bf83d3 100644
--- a/clients/web/pnpm-lock.yaml
+++ b/clients/web/pnpm-lock.yaml
@@ -48,6 +48,9 @@ catalogs:
     happy-dom:
       specifier: 20.8.3
       version: 20.8.3
+    portless:
+      specifier: 0.6.0
+      version: 0.6.0
     postcss:
       specifier: 8.5.8
       version: 8.5.8
@@ -157,6 +160,9 @@ importers:
       happy-dom:
         specifier: 'catalog:'
         version: 20.8.3
+      portless:
+        specifier: 'catalog:'
+        version: 0.6.0
       postcss:
         specifier: 'catalog:'
         version: 8.5.8
@@ -227,6 +233,9 @@ importers:
       happy-dom:
         specifier: 'catalog:'
         version: 20.8.3
+      portless:
+        specifier: 'catalog:'
+        version: 0.6.0
       postcss:
         specifier: 'catalog:'
         version: 8.5.8
@@ -267,6 +276,9 @@ importers:
       astro-vtbot:
         specifier: 'catalog:'
         version: 2.1.11
+      portless:
+        specifier: 'catalog:'
+        version: 0.6.0
       typescript:
         specifier: 'catalog:'
         version: 5.9.3
@@ -286,6 +298,9 @@ importers:
         specifier: 'catalog:'
         version: 0.34.5
     devDependencies:
+      portless:
+        specifier: 'catalog:'
+        version: 0.6.0
       typescript:
         specifier: 'catalog:'
         version: 5.9.3
@@ -2644,6 +2659,12 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
+  portless@0.6.0:
+    resolution: {integrity: sha512-Jjk36bsWGTrqo+uyfKtHaXOfXq80BJ5EOdIRCWCbhYyJ04uV8dVw9/G4u31u1zQWmcE5WrZEYMGAm5XE+tDtXg==}
+    engines: {node: '>=20'}
+    os: [darwin, linux]
+    hasBin: true
+
   postcss-nested@6.2.0:
     resolution: {integrity: sha512-HQbt28KulC5AJzG+cZtj9kvKB93CFCdLvog1WFLf1D+xmMvPGlBstkpTEZfK5+AN9hfJocyBFCNiqyS48bpgzQ==}
     engines: {node: '>=12.0'}
@@ -6225,6 +6246,10 @@ snapshots:
     optionalDependencies:
       fsevents: 2.3.2
 
+  portless@0.6.0:
+    dependencies:
+      chalk: 5.6.2
+
   postcss-nested@6.2.0(postcss@8.5.8):
     dependencies:
       postcss: 8.5.8
diff --git a/clients/web/pnpm-workspace.yaml b/clients/web/pnpm-workspace.yaml
index 4f6252941..3dae0461d 100644
--- a/clients/web/pnpm-workspace.yaml
+++ b/clients/web/pnpm-workspace.yaml
@@ -18,6 +18,7 @@ catalog:
   astro-vtbot: 2.1.11
   happy-dom: 20.8.3
   postcss: 8.5.8
+  portless: 0.6.0
   sharp: 0.34.5
   tailwind-merge: 3.5.0
   tailwindcss: 4.2.1