[docs] Document run script and Dockerfile conflict for AddJavaScriptApp

src/frontend/src/content/docs/deployment/javascript-apps.mdx

@@ -1221,6 +1221,49 @@ The `DisableBuildOnlyContainerValidation` method is marked experimental with the
 
 `AddNextJsApp` is different because it represents the Next.js standalone-server publish model directly. Use it when the app is a Next.js app with `output: "standalone"` rather than modeling the app with `AddJavaScriptApp` and choosing a generic npm-script publish method.
 
+### Run script and existing Dockerfile conflict
+
+When `AddJavaScriptApp` finds an existing user-authored `Dockerfile` in the app directory, Aspire uses that Dockerfile as the publish container image and cannot safely replace its `ENTRYPOINT`. If you also pass an explicit `runScriptName` to `AddJavaScriptApp` or call `.WithRunScript(...)` with a non-default script name, Aspire fails at publish time with a clear error rather than silently emitting an image that ignores the requested script:
+
+```text
+JavaScript app resource 'js' is configured to run script 'migrate', but publish is using the existing Dockerfile 'Dockerfile'. An existing Dockerfile entrypoint cannot be changed automatically from runScriptName or WithRunScript. Remove or rename the Dockerfile so Aspire can generate one, or call PublishAsDockerFile(...) and set the container entrypoint explicitly.
+```
+
+To resolve the conflict, choose one of the following options:
+
+- **Remove or rename the Dockerfile** so Aspire generates a new one that runs your requested script as the container entrypoint.
+- **Override the container entrypoint explicitly** by calling `PublishAsDockerFile(...)` and configuring the entrypoint directly on the container resource. This keeps the existing Dockerfile and gives you full control over what runs:
+
+<Tabs syncKey='aspire-lang'>
+<TabItem id='csharp' label='C#'>
+
+```csharp title="AppHost.cs"
+builder
+    .AddJavaScriptApp("js", "./js", runScriptName: "migrate")
+    .WithBun()
+    .PublishAsDockerFile(container => container
+        .WithEntrypoint("bun")
+        .WithArgs("src/migrate.ts"));
+```
+
+</TabItem>
+<TabItem id='typescript' label='TypeScript'>
+
+```typescript title="apphost.ts"
+await builder
+  .addJavaScriptApp('js', './js', { runScriptName: 'migrate' })
+  .withBun()
+  .publishAsDockerFile(async container => {
+    container.withEntrypoint('bun');
+    container.withArgs(['src/migrate.ts']);
+  });
+```
+
+</TabItem>
+</Tabs>
+
+Using the implicit default `runScriptName` (`"dev"`) without any custom arguments is always allowed, even when an existing Dockerfile is present, because no script override is actually requested in that case.
+
 ## Common mistakes
 
 - Expecting `AddViteApp` or `AddJavaScriptApp` to be the deployed production web server without choosing a publish method.
@@ -1231,6 +1274,7 @@ The `DisableBuildOnlyContainerValidation` method is marked experimental with the
 - Calling `.WithHttpEndpoint()` on `AddViteApp`.
 - Using `VITE_*` variables for values that must be resolved at runtime in an already-built SPA.
 - Adding a Vite or JavaScript app without choosing a production serving model, which causes a publish/deploy validation error for an unconsumed build-only container.
+- Passing an explicit `runScriptName` or calling `.WithRunScript(...)` when the app directory already has a user-authored Dockerfile, which causes a publish-time conflict error. Remove the Dockerfile or use `PublishAsDockerFile(...)` with an explicit container entrypoint to resolve the conflict.
 
 <LearnMore>
   For runtime configuration guidance, see [JavaScript