@promptbook/cli 0.114.0-0 → 0.114.0-10

package/README.md

@@ -215,8 +215,6 @@ Respond to incoming legal inquiries via email and keep the company website updat
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
 <br/>
-USE EMAIL<br/>
-USE BROWSER<br/>
 <br/>
 TEAM You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law.<br/>
 
@@ -305,7 +303,7 @@ GOAL Keep the company website updated with the latest legal policies and complia
 
 #### `Use` commitments
 
-Use commitments grant the agent real capabilities - tools it can use to interact with the outside world. `USE EMAIL` lets the agent send emails, `USE BROWSER` lets it access and read web content, `USE SEARCH ENGINE` lets it search the web, and many more.
+Use commitments grant the agent real capabilities - tools it can use to interact with the outside world. `USE CALENDAR` lets the agent work with a calendar, `USE PROJECT` gives it access to a code repository, `USE MCP` connects any external Model Context Protocol server, and many more.
 
 These are what turn a chatbot into a persistent agent that actually does work.
 
@@ -322,9 +320,6 @@ GOAL Keep the company website updated with the latest legal policies and complia
 **RULE** Never provide legal advice about criminal law.<br/>
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
-USE EMAIL<br/>
-USE BROWSER<br/>
-USE SEARCH ENGINE<br/>
 
 </td></tr></table>
 
@@ -345,9 +340,6 @@ GOAL Keep the company website updated with the latest legal policies and complia
 **RULE** Never provide legal advice about criminal law.<br/>
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
-USE EMAIL<br/>
-USE BROWSER<br/>
-USE SEARCH ENGINE<br/>
 TEAM You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law.<br/>
 
 </td></tr></table>
@@ -534,7 +526,7 @@ Or you can install them separately:
 
 Promptbook Coder is **not another standalone coding model**. It is an orchestration layer over coding agents such as **GitHub Copilot**, **OpenAI Codex**, **Claude Code**, **Opencode**, **Cline**, and **Gemini CLI**. The difference is that Promptbook Coder adds a repeatable repository workflow on top of them:
 
--   prompt files with explicit statuses like `[ ]`, `[x]`, and `[-]`
+-   prompt files with explicit statuses like `[ ]`, `[^]`, `[x]`, and `[-]`
 -   automatic selection of the next runnable task, including priority support
 -   optional shared repo context loaded from a file such as `AGENTS.md`
 -   automatic `git add`, commit, and push after each successful prompt
@@ -549,11 +541,11 @@ In short: tools like Claude Code, Codex, or GitHub Copilot are the **engines**;
 1. `ptbk coder init` prepares the project for the coder workflow, seeds project-owned generic templates in `prompts/templates/`, creates a starter `AGENTS.md` context file, adds helper `npm run coder:*` scripts, ensures `.gitignore` ignores `/.promptbook`, and configures VS Code prompt screenshots in `prompts/screenshots/`.
 2. `ptbk coder generate-boilerplates` creates prompt files in `prompts/`.
 3. You replace placeholder `@@@` sections with real coding tasks.
-4. `ptbk coder run` sends the next ready `[ ]` prompt to the selected coding agent.
+4. `ptbk coder run` sends the next ready `[ ]` prompt to the selected coding agent and immediately marks it as in progress `[^]`, naming the harness, the model and the step which is running.
 5. Promptbook Coder marks the prompt as done `[x]`, records runner metadata, then stages, commits, and pushes the resulting changes.
 6. `ptbk coder verify` reviews completed prompts, archives finished files to `prompts/done/`, and appends a repair prompt when more work is needed.
 
-Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treated as not fully written, and prompts with more `!` markers have higher priority.
+Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treated as not fully written, and prompts with more `!` markers have higher priority. A prompt left as `[^]` was interrupted in the middle of its implementation — the in-progress status is never reverted, so a killed or crashed coder always leaves that signal behind.
 
 #### Features
 
@@ -625,26 +617,27 @@ ptbk coder verify
 | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------ | ---- | ----- | ------------------------------------------------------------------------ |
 | `ptbk coder init`                     | Creates `prompts/`, `prompts/done/`, the project-generic template files materialized in `prompts/templates/` (currently `common.md`), and a starter `AGENTS.md`; ensures `.env` contains `CODING_AGENT_GIT_NAME`, `CODING_AGENT_GIT_EMAIL`, and `CODING_AGENT_GIT_SIGNING_KEY`; adds helper coder scripts to `package.json`; ensures `.gitignore` contains `/.promptbook`; and configures `.vscode/settings.json` to save pasted prompt images into `prompts/screenshots/`. |
 | `ptbk coder generate-boilerplates`    | Creates new prompt markdown files with fresh emoji tags so you can quickly fill in coding tasks; `--template` accepts either a built-in alias or a markdown file path relative to the project root.                                                                                                                                                                                                                                                                         |
-| `ptbk coder run`                      | Picks the next ready prompt, appends optional context, runs it through the selected coding agent, can optionally verify each attempt with a shell test command and feed failing output back for retries, then marks success or failure, commits the result, and pushes only when `--auto-push` is enabled.                                                                                                                                                                  |
+| `ptbk coder run`                      | Picks the next ready prompt, can run tests before coding to stop or repair pre-existing failures, appends optional context, runs it through the selected coding agent, can optionally verify each attempt with a shell test command and feed failing output back for retries, then marks success or failure, commits the result, and pushes only when `--auto-push` is enabled.                                                                                             |
 | `ptbk coder find-refactor-candidates` | Scans the repository for oversized or overpacked files and writes prompt files for likely refactors; `--level <xlow                                                                                                                                                                                                                                                                                                                                                         | low | medium | high | xhigh | extreme>` ranges from a very benevolent scan to a very aggressive sweep. |
 | `ptbk coder verify`                   | Walks through completed prompts, archives truly finished work, and adds follow-up repair prompts for unfinished results.                                                                                                                                                                                                                                                                                                                                                    |
 
 #### Most useful `ptbk coder run` flags
 
-| Flag                       | Purpose                                                                                            |
-| -------------------------- | -------------------------------------------------------------------------------------------------- |
-| `--harness <name>`         | Selects the coding harness.                                                                        |
-| `--model <model>`          | Chooses the runner model; required for `openai-codex` and `gemini`, optional for `github-copilot`. |
-| `--context <text-or-file>` | Appends extra instructions inline or from a file like `AGENTS.md`.                                 |
-| `--test <command>`         | Runs a verification command after each prompt attempt and feeds failing output back for retries.   |
-| `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                       |
-| `--no-auto`                | Waits for user confirmation before each prompt instead of running automatically through the queue. |
-| `--ignore-git-changes`     | Disables the clean-working-tree guard.                                                             |
-| `--priority <n>`           | Runs only prompts at or above the given priority.                                                  |
-| `--dry-run`                | Prints which prompts are ready instead of executing them.                                          |
-| `--allow-credits`          | Lets OpenAI Codex spend credits when required.                                                     |
-| `--auto-push`              | Pushes each successful coding-agent commit to the configured remote.                               |
-| `--auto-migrate`           | Runs testing-server database migrations after each successful prompt.                              |
+| Flag                       | Purpose                                                                                                                                                                                |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--harness <name>`         | Selects the coding harness.                                                                                                                                                            |
+| `--model <model>`          | Chooses the runner model; required for `openai-codex` and `gemini`, optional for `github-copilot`.                                                                                     |
+| `--context <text-or-file>` | Appends extra instructions inline or from a file like `AGENTS.md`.                                                                                                                     |
+| `--test <command>`         | Runs a verification command after each prompt attempt and feeds failing output back for retries.                                                                                       |
+| `--test-before <mode>`     | Runs tests before coding: `no` (default), `yes-and-fail` (stop with results), or `yes-and-fix` (create one repair prompt first); defaults to `npm test` when enabled without `--test`. |
+| `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                                                                                                           |
+| `--no-auto`                | Waits for user confirmation before each prompt instead of running automatically through the queue.                                                                                     |
+| `--ignore-git-changes`     | Disables the clean-working-tree guard.                                                                                                                                                 |
+| `--priority <n>`           | Runs only prompts at or above the given priority.                                                                                                                                      |
+| `--dry-run`                | Prints which prompts are ready instead of executing them.                                                                                                                              |
+| `--allow-credits`          | Lets OpenAI Codex spend credits when required.                                                                                                                                         |
+| `--auto-push`              | Pushes each successful coding-agent commit to the configured remote.                                                                                                                   |
+| `--auto-migrate`           | Runs testing-server database migrations after each successful prompt.                                                                                                                  |
 
 #### Typical usage pattern
 

package/agents/default/developer.book

@@ -2,6 +2,7 @@ Developer
 
 
 
+META VISUAL ascii-octopus
 META VISIBILITY PRIVATE
 
 RULE

package/apps/agents-server/README.md

@@ -45,7 +45,7 @@ ptbk agents-server start --harness github-copilot --model gpt-5.4 --thinking-lev
 -   `SESSION_SECRET`: HMAC signing key used to sign the session cookie. Must be set explicitly in production — the server refuses to start session signing when missing instead of falling back to a hardcoded default. Use a long random string, for example the output of `openssl rand -hex 32`. Keep it separate from `ADMIN_PASSWORD` so a leak of either credential cannot forge the other.
 
 <a id="agents-server-env-ptbk-agents-server-user-chat-worker-token"></a>
--   `PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN`: Shared internal token used to authorize background worker routes (`/api/internal/user-chat-jobs/run`, `/api/internal/user-chat-timeouts/run`, and `/api/internal/agent-runner-limits`). Must be set explicitly in production — the server refuses to resolve the worker token when missing instead of falling back to `ADMIN_PASSWORD`, `SUPABASE_SERVICE_ROLE_KEY`, or a hardcoded constant. Use a long random string, for example the output of `openssl rand -hex 32`. The CLI launcher (`ptbk agents-server start`) generates a per-process value automatically when the variable is empty so local development works without configuration.
+-   `PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN`: Shared internal token used to authorize managed-agent and background worker routes (including `/api/internal/user-chat-jobs/run`, `/api/internal/user-chat-timeouts/run`, `/api/internal/agent-goal-chat-planned-messages`, and `/api/internal/agent-runner-limits`). Must be set explicitly in production — the server refuses to resolve the worker token when missing instead of falling back to `ADMIN_PASSWORD`, `SUPABASE_SERVICE_ROLE_KEY`, or a hardcoded constant. Use a long random string, for example the output of `openssl rand -hex 32`. The CLI launcher (`ptbk agents-server start`) generates a per-process value automatically when the variable is empty so local development works without configuration.
 
 <a id="agents-server-env-promptbook-team-agent-access-token"></a>
 -   `PROMPTBOOK_TEAM_AGENT_ACCESS_TOKEN`: Dedicated secret used by same-server `TEAM` calls to authorize access to private teammate agents. Must be a dedicated random string — falling back to `ADMIN_PASSWORD` or `SUPABASE_SERVICE_ROLE_KEY` would let a leak of one credential compromise both authentication boundaries. When not configured, same-server team access stays disabled (the integration fails closed) so leaving the variable empty is safe but disables the feature. Use a long random string, for example the output of `openssl rand -hex 32`.

package/apps/agents-server/{USE_TIMEOUT_CHIP_QA.md → TIMEOUT_CHIP_QA.md}

@@ -1,4 +1,4 @@
-# USE TIMEOUT Chip QA
+# Timeout Chip QA
 
 -   Friendly default popup:
     Trigger a `set_timeout` tool call in an agent chat, click the timeout chip under the assistant message, and confirm the first view shows friendly copy (for example `Will retry in ...`) plus local time, relative time, and timezone.

package/apps/agents-server/next.config.ts

@@ -22,6 +22,11 @@ const agentsServerNodeModulesPath = process.env.PTBK_AGENTS_SERVER_NODE_MODULES_
  */
 const isNextValidationIgnored = process.env.PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION === 'true';
 
+/**
+ * Whether one isolated CLI production build should avoid writing a webpack filesystem cache that no later release can reuse.
+ */
+const isWebpackFilesystemCacheDisabled = process.env.PTBK_AGENTS_SERVER_DISABLE_WEBPACK_FILESYSTEM_CACHE === 'true';
+
 /**
  * Optional worker count override for CLI-owned production builds on memory-constrained VPS hosts.
  */
@@ -29,6 +34,15 @@ const AGENTS_SERVER_BUILD_WORKER_COUNT = parseAgentsServerBuildWorkerCount(
     process.env.PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT,
 );
 
+/**
+ * Whether this build has to stay inside a small memory budget.
+ *
+ * Standalone VPS self-updates request a single build worker because they compile the replacement
+ * server while the current one is still serving traffic, so such a build must not start additional
+ * concurrent work either.
+ */
+const IS_MEMORY_CONSTRAINED_BUILD = AGENTS_SERVER_BUILD_WORKER_COUNT === 1;
+
 /**
  * Whether Sentry source maps can be uploaded during production builds.
  */
@@ -64,6 +78,19 @@ const nextConfig: NextConfig = {
 
     experimental: {
         externalDir: true,
+
+        // Note: Next.js turns its build workers off as soon as a `webpack` function is configured, and
+        //       that also turns off the parallel output file tracing pass. The `webpack` function below
+        //       only adds aliases, fallbacks and loaders, so the workers are asked for explicitly.
+        //       Compiling each target in a separate short-lived process also releases its memory as
+        //       soon as that target is done.
+        webpackBuildWorker: true,
+
+        // Note: Collecting the output file traces takes about two minutes and used to run alone between
+        //       the compilation and the static generation. It now runs next to the remaining compilation
+        //       and page generation - except for a build which has to save memory rather than time.
+        parallelServerBuildTraces: !IS_MEMORY_CONSTRAINED_BUILD,
+
         ...(AGENTS_SERVER_BUILD_WORKER_COUNT ? { cpus: AGENTS_SERVER_BUILD_WORKER_COUNT } : {}),
     },
 
@@ -79,6 +106,12 @@ const nextConfig: NextConfig = {
     },
 
     webpack(config, { isServer, nextRuntime }) {
+        if (isWebpackFilesystemCacheDisabled) {
+            // Versioned VPS releases build into a fresh checkout. Persisting the multi-gigabyte webpack cache there
+            // adds substantial disk I/O but cannot accelerate the next release, which has a different checkout.
+            config.cache = false;
+        }
+
         config.resolve.alias = {
             ...config.resolve.alias,
             '@': path.resolve(__dirname),

package/apps/agents-server/package.json

@@ -1,17 +1,19 @@
 {
     "name": "promptbook-agents-server",
     "scripts": {
-        "generate-reserved-paths": "ts-node ./scripts/generate-reserved-paths/generate-reserved-paths.ts",
-        "prebuild": "npm run generate-reserved-paths && node ./scripts/clearNextGeneratedTypes.js && npx kill-port 4440 ||  exit 0",
-        "predev": "npm run generate-reserved-paths && npx kill-port 4440 ||  exit 0",
+        "generate-reserved-paths": "ts-node --transpile-only ./scripts/generate-reserved-paths/generate-reserved-paths.ts",
+        "prebuild": "npm run generate-reserved-paths && node ./scripts/clearNextGeneratedTypes.js && node ./scripts/kill-port.js 4440",
+        "predev": "npm run generate-reserved-paths && node ./scripts/kill-port.js 4440",
         "dev": "next dev -p 4440",
-        "test": "npm run lint && npm run test-build && npm run test-e2e",
-        "test-e2e": "playwright test",
-        "pretest-build": "npx kill-port 4021 4440 || exit 0",
+        "test": "npm run test-e2e",
+        "test-e2e": "node ./scripts/run-e2e-tests.js",
+        "pretest-build": "node ./scripts/kill-port.js 4021 4440",
         "test-build": "npm run build",
-        "build": "node --max-old-space-size=8192 -r ./scripts/ignore-kill-eperm.js ./scripts/next-cli.js build && node ./scripts/prerender-homepage.js",
+        "pretest-e2e": "node ./scripts/kill-port.js 4021 4440",
+        "build": "node ./scripts/build-agents-server.js",
+        "build-e2e": "node ./scripts/build-e2e.js",
         "start": "next start -p 4440",
-        "lint": "eslint src/ --max-warnings=0",
-        "postinstall": "cd ../../ && npm ci"
+        "lint": "eslint src/ --max-warnings=0 --cache --cache-location ./node_modules/.cache/eslint/agents-server-src.json",
+        "postinstall": "node ./scripts/ensure-root-dependencies.js"
     }
 }

package/apps/agents-server/playwright.config.ts

@@ -2,54 +2,45 @@ import path from 'path';
 import { defineConfig, devices } from 'playwright/test';
 
 /**
- * Local host and port used by the mocked Supabase API during integration tests.
+ * Shape of the shared CommonJS module used by the E2E build, server, and Playwright configuration.
  */
-const MOCK_SUPABASE_PORT = 54321;
-
-/**
- * Base URL served by the mocked Supabase API.
- */
-const MOCK_SUPABASE_URL = `http://127.0.0.1:${MOCK_SUPABASE_PORT}`;
+type E2eEnvironmentModule = {
+    readonly APP_E2E_ENV: Readonly<Record<string, string>>;
+    readonly APP_PORT: number;
+    readonly APP_URL: string;
+    readonly MOCK_SUPABASE_PORT: number;
+    readonly MOCK_SUPABASE_URL: string;
+};
 
-/**
- * Local host and port used by the Agents Server application during integration tests.
- */
-const APP_PORT = 4440;
+const {
+    APP_E2E_ENV,
+    APP_PORT,
+    APP_URL,
+    MOCK_SUPABASE_PORT,
+    MOCK_SUPABASE_URL,
+} = require('./tests/e2e/e2eEnvironment.cjs') as E2eEnvironmentModule;
 
 /**
- * Base URL served by the Agents Server application during integration tests.
+ * Maximum time allowed for the production Agents Server bundle used by browser tests.
  */
-const APP_URL = `http://127.0.0.1:${APP_PORT}`;
+const E2E_WEB_SERVER_TIMEOUT_MS = 30 * 60 * 1000;
 
 /**
- * Maximum time allowed for the production Agents Server bundle used by browser tests.
+ * Directory under the repository root that should hold Playwright artifacts such as recorded videos.
  */
-const E2E_WEB_SERVER_TIMEOUT_MS = 30 * 60 * 1000;
+const E2E_ARTIFACTS_DIR = path.join(__dirname, '..', '..', 'other', 'integration-tests', 'videos');
 
 /**
- * Shared environment variables required by the Agents Server in deterministic e2e runs.
+ * Uses the already prepared production build when the test runner created it.
+ * Direct Playwright invocations keep the self-bootstrapping build behavior.
  */
-const APP_E2E_ENV = {
-    ADMIN_PASSWORD: 'e2e-admin-password',
-    SESSION_SECRET: 'e2e-session-secret-must-differ-from-admin-password',
-    PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN: 'e2e-user-chat-worker-token-must-differ-from-admin-password',
-    PROMPTBOOK_TEAM_AGENT_ACCESS_TOKEN: 'e2e-team-agent-access-token-must-differ-from-admin-password',
-    NEXT_DIST_DIR: '.next-e2e',
-    NEXT_PUBLIC_SITE_URL: APP_URL,
-    PTBK_AGENTS_SERVER_DATABASE: 'supabase',
-    PTBK_AGENTS_SERVER_SQLITE_PATH: '',
-    SUPABASE_TABLE_PREFIX: '',
-    POSTGRES_URL: '',
-    DATABASE_URL: '',
-    NEXT_PUBLIC_SUPABASE_URL: MOCK_SUPABASE_URL,
-    NEXT_PUBLIC_SUPABASE_ANON_KEY: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYW5vbiJ9.e2e-signature',
-    SUPABASE_SERVICE_ROLE_KEY: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoic2VydmljZV9yb2xlIn0.e2e-signature',
-};
+const E2E_APP_WEB_SERVER_COMMAND =
+    process.env.PTBK_E2E_BUILD_READY === 'true' ? 'npm run start' : 'node ./scripts/build-e2e.js --start';
 
 /**
- * Directory under the repository root that should hold Playwright artifacts such as recorded videos.
+ * Environment inherited by the local E2E web servers.
  */
-const E2E_ARTIFACTS_DIR = path.join(__dirname, '..', '..', 'other', 'integration-tests', 'videos');
+const PROCESS_ENVIRONMENT = process.env as Record<string, string>;
 
 /**
  * Playwright configuration for Agents Server integration tests.
@@ -88,7 +79,7 @@ const config = defineConfig({
             stdout: 'pipe',
             stderr: 'pipe',
             env: {
-                ...process.env,
+                ...PROCESS_ENVIRONMENT,
                 E2E_SUPABASE_PORT: String(MOCK_SUPABASE_PORT),
                 E2E_SERVER_NAME: 'local-e2e',
                 E2E_SERVER_ENVIRONMENT: 'PREVIEW',
@@ -97,8 +88,7 @@ const config = defineConfig({
             },
         },
         {
-            command:
-                'npm run prebuild && node --max-old-space-size=8192 -r ./scripts/ignore-kill-eperm.js ./scripts/next-cli.js build && npm run start',
+            command: E2E_APP_WEB_SERVER_COMMAND,
             cwd: __dirname,
             url: APP_URL,
             reuseExistingServer: false,
@@ -106,7 +96,7 @@ const config = defineConfig({
             stdout: 'pipe',
             stderr: 'pipe',
             env: {
-                ...process.env,
+                ...PROCESS_ENVIRONMENT,
                 ...APP_E2E_ENV,
             },
         },

package/apps/agents-server/scripts/build-agents-server.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+/**
+ * Root directory of the Agents Server app.
+ */
+const APP_ROOT = path.resolve(__dirname, '..');
+
+/**
+ * Root directory of the repository, which owns the shared build and test scripts.
+ */
+const PROJECT_ROOT = path.resolve(APP_ROOT, '..', '..');
+
+/**
+ * Maximum Node.js heap size used by the Next.js production build.
+ */
+const AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB = 8192;
+
+/**
+ * Runs the shared Agents Server production build and its homepage prerender step.
+ *
+ * The optional `--no-lint` argument is used by the E2E runner after the same app
+ * lint command has already completed successfully. The optional `--no-homepage-prerender`
+ * argument is used by builds whose caller starts the very same production server right
+ * afterwards, which makes the extra prerender server a repetition of that work.
+ */
+function buildAgentsServer() {
+    const nextBuildArguments = [
+        '-r',
+        path.join(PROJECT_ROOT, 'scripts', 'ignore-kill-eperm.js'),
+        path.join(APP_ROOT, 'scripts', 'next-cli.js'),
+        'build',
+    ];
+
+    if (process.argv.includes('--no-lint')) {
+        nextBuildArguments.push('--no-lint');
+    }
+
+    runChildProcess(process.execPath, nextBuildArguments, {
+        // Note: Next.js compiles each webpack target in its own build worker process, and a worker
+        //       inherits the heap limit only through `NODE_OPTIONS` - not through the command line of
+        //       the build process which spawned it. The same merge is done for the CLI-owned
+        //       production build in `src/cli/cli-commands/agents-server/buildAgentsServer/runNextBuild.ts`.
+        NODE_OPTIONS: mergeNodeOptionsWithHeapSize(process.env.NODE_OPTIONS, AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB),
+    });
+
+    if (!process.argv.includes('--no-homepage-prerender')) {
+        runChildProcess(process.execPath, [path.join(APP_ROOT, 'scripts', 'prerender-homepage.js')]);
+    }
+}
+
+/**
+ * Prepends `--max-old-space-size=<mib>` to `NODE_OPTIONS` unless the caller already set one.
+ *
+ * @param existingNodeOptions - Inherited `NODE_OPTIONS` value.
+ * @param maxOldSpaceMib - Maximum Node.js heap size in MiB.
+ * @returns `NODE_OPTIONS` value for the build process.
+ */
+function mergeNodeOptionsWithHeapSize(existingNodeOptions, maxOldSpaceMib) {
+    if (existingNodeOptions !== undefined && /--max-old-space-size[= ]/u.test(existingNodeOptions)) {
+        return existingNodeOptions;
+    }
+
+    const heapFlag = `--max-old-space-size=${maxOldSpaceMib}`;
+
+    return existingNodeOptions ? `${heapFlag} ${existingNodeOptions}` : heapFlag;
+}
+
+/**
+ * Runs one child process and forwards its exit status.
+ *
+ * @param executablePath - Executable to run.
+ * @param argumentsList - Arguments passed to the executable.
+ * @param environmentOverrides - Environment variables added on top of the inherited environment.
+ */
+function runChildProcess(executablePath, argumentsList, environmentOverrides = {}) {
+    const result = spawnSync(executablePath, argumentsList, {
+        cwd: APP_ROOT,
+        env: {
+            ...process.env,
+            ...environmentOverrides,
+        },
+        stdio: 'inherit',
+    });
+
+    if (result.error) {
+        console.error(`Failed to run ${executablePath}:`, result.error);
+        process.exit(1);
+    }
+
+    if (result.status !== 0) {
+        process.exit(result.status ?? 1);
+    }
+}
+
+buildAgentsServer();

package/apps/agents-server/scripts/build-e2e.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const path = require('node:path');
+const { APP_E2E_ENV } = require('../tests/e2e/e2eEnvironment.cjs');
+const { runNpm } = require('./run-npm.js');
+
+/**
+ * Root directory of the Agents Server app.
+ */
+const APP_ROOT = path.resolve(__dirname, '..');
+
+/**
+ * Production build arguments which every E2E build applies.
+ *
+ * The homepage prerender starts one more production server only to download `/` into an HTML
+ * snapshot which nothing reads afterwards. Every E2E build is started by Playwright right after it
+ * is compiled, and the tests open the homepage against that very same server, so the snapshot would
+ * only repeat work the tests already do.
+ */
+const E2E_BUILD_ARGUMENTS = ['--no-homepage-prerender'];
+
+/**
+ * Builds the production bundle used by the Agents Server E2E tests.
+ *
+ * The E2E environment is applied while compiling so public values such as the
+ * mocked Supabase URL are embedded consistently in browser bundles.
+ */
+function buildE2eServer() {
+    const buildArguments = ['run', 'build', '--', ...E2E_BUILD_ARGUMENTS];
+
+    if (process.argv.includes('--no-lint')) {
+        buildArguments.push('--no-lint');
+    }
+
+    runNpm(buildArguments, {
+        cwd: APP_ROOT,
+        environmentOverrides: APP_E2E_ENV,
+    });
+
+    if (process.argv.includes('--start')) {
+        runNpm(['run', 'start'], {
+            cwd: APP_ROOT,
+            environmentOverrides: APP_E2E_ENV,
+        });
+    }
+}
+
+buildE2eServer();

package/apps/agents-server/scripts/ensure-root-dependencies.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const { createHash } = require('node:crypto');
+const { createRequire } = require('node:module');
+const { existsSync, readFileSync, writeFileSync } = require('node:fs');
+const path = require('node:path');
+const { runNpm } = require('./run-npm.js');
+
+/**
+ * Root directory whose dependency tree is used by the Agents Server app.
+ */
+const REPOSITORY_ROOT = path.resolve(__dirname, '..', '..');
+
+/**
+ * Root package lock file used to validate the installed dependency tree.
+ */
+const PACKAGE_LOCK_FILE_PATH = path.join(REPOSITORY_ROOT, 'package-lock.json');
+
+/**
+ * Marker persisted inside `node_modules` after a successful root dependency installation.
+ */
+const ROOT_DEPENDENCY_MARKER_PATH = path.join(
+    REPOSITORY_ROOT,
+    'node_modules',
+    '.promptbook-package-lock-hash',
+);
+
+/**
+ * Small set of packages required to recognize a usable root dependency tree.
+ */
+const REQUIRED_ROOT_PACKAGE_NAMES = ['next', 'typescript', 'ts-node', '@playwright/test'];
+
+/**
+ * Ensures that installing the nested app does not reinstall the root dependency tree on every run.
+ */
+function ensureRootDependencies() {
+    const packageLockHash = createPackageLockHash();
+
+    if (isRootDependencyTreeCurrent(packageLockHash)) {
+        return;
+    }
+
+    runNpm(['ci', '--include=dev', '--prefer-offline', '--no-audit', '--no-fund'], {
+        cwd: REPOSITORY_ROOT,
+    });
+
+    writeFileSync(ROOT_DEPENDENCY_MARKER_PATH, `${packageLockHash}\n`, 'utf8');
+}
+
+/**
+ * Creates a stable hash for the root package lock file.
+ *
+ * @returns SHA-256 hash of the package lock contents.
+ */
+function createPackageLockHash() {
+    return createHash('sha256').update(readFileSync(PACKAGE_LOCK_FILE_PATH)).digest('hex');
+}
+
+/**
+ * Checks whether the root dependency tree matches the current package lock file.
+ *
+ * @param packageLockHash - Expected package lock hash.
+ * @returns Whether the existing root dependency tree can be reused.
+ */
+function isRootDependencyTreeCurrent(packageLockHash) {
+    if (!existsSync(ROOT_DEPENDENCY_MARKER_PATH)) {
+        return false;
+    }
+
+    if (readFileSync(ROOT_DEPENDENCY_MARKER_PATH, 'utf8').trim() !== packageLockHash) {
+        return false;
+    }
+
+    const rootRequire = createRequire(path.join(REPOSITORY_ROOT, 'package.json'));
+
+    return REQUIRED_ROOT_PACKAGE_NAMES.every((packageName) => {
+        try {
+            rootRequire.resolve(`${packageName}/package.json`);
+            return true;
+        } catch {
+            return false;
+        }
+    });
+}
+
+ensureRootDependencies();

package/apps/agents-server/scripts/generate-reserved-paths/generate-reserved-paths.ts

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import fs from 'fs';
 import path from 'path';
 import { GENERATOR_WARNING } from '../../../../src/config';
@@ -58,18 +59,20 @@ const allReservedPaths = [...new Set([...reservedPaths, ...publicPaths, ...addit
 /**
  * Constant for content.
  */
-const content = `/**
- * Reserved paths that should not be treated as agent names.
- * This file is auto-generated by scripts/generate-reserved-paths.js
- *
- * ${GENERATOR_WARNING}
- *
- * @see /apps/agents-server/src/app - source directory for routes
- * @see /apps/agents-server/public - source directory for static files
- * @see /apps/agents-server/src/middleware.ts - where this is used
- */
-export const RESERVED_PATHS: readonly string[] = ${JSON.stringify(allReservedPaths, null, 4)} as const;
-`;
+const content = spaceTrim(
+    (block) => `/**
+     * Reserved paths that should not be treated as agent names.
+     * This file is auto-generated by scripts/generate-reserved-paths.js
+     *
+     * ${GENERATOR_WARNING}
+     *
+     * @see /apps/agents-server/src/app - source directory for routes
+     * @see /apps/agents-server/public - source directory for static files
+     * @see /apps/agents-server/src/middleware.ts - where this is used
+     */
+    export const RESERVED_PATHS: readonly string[] = ${block(JSON.stringify(allReservedPaths, null, 4))} as const;
+    `,
+);
 
 // Ensure the generated directory exists
 /**
@@ -80,8 +83,19 @@ if (!fs.existsSync(generatedDir)) {
     fs.mkdirSync(generatedDir, { recursive: true });
 }
 
-// Write the file
-fs.writeFileSync(outputFile, content, 'utf-8');
+// Note: Rewriting an unchanged file would only move its modification time forward, which invalidates
+//       the webpack and TypeScript caches of every build and every development server start.
+/**
+ * Constant for current content.
+ */
+const currentContent = fs.existsSync(outputFile) ? fs.readFileSync(outputFile, 'utf-8') : null;
 
-console.log(`Generated ${outputFile} with ${allReservedPaths.length} reserved paths:`);
-console.log(allReservedPaths.join(', '));
+if (currentContent === content) {
+    console.log(`Kept ${outputFile} unchanged with ${allReservedPaths.length} reserved paths.`);
+} else {
+    // Write the file
+    fs.writeFileSync(outputFile, content, 'utf-8');
+
+    console.log(`Generated ${outputFile} with ${allReservedPaths.length} reserved paths:`);
+    console.log(allReservedPaths.join(', '));
+}