@promptbook/cli 0.114.0-1 → 0.114.0-3

package/README.md

@@ -625,26 +625,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/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.
  */
@@ -79,6 +84,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

@@ -5,13 +5,15 @@
         "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",
         "dev": "next dev -p 4440",
-        "test": "npm run lint && npm run test-build && npm run test-e2e",
-        "test-e2e": "playwright test",
+        "test": "npm run test-e2e",
+        "test-e2e": "node ./scripts/run-e2e-tests.js",
         "pretest-build": "npx kill-port 4021 4440 || exit 0",
         "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": "npx kill-port 4021 4440 || exit 0",
+        "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"
+        "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,62 @@
+'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, '..');
+
+/**
+ * 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.
+ */
+function buildAgentsServer() {
+    const nextBuildArguments = [
+        `--max-old-space-size=${AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB}`,
+        '-r',
+        path.join(APP_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);
+    runChildProcess(process.execPath, [path.join(APP_ROOT, 'scripts', 'prerender-homepage.js')]);
+}
+
+/**
+ * Runs one child process and forwards its exit status.
+ *
+ * @param executablePath - Executable to run.
+ * @param argumentsList - Arguments passed to the executable.
+ */
+function runChildProcess(executablePath, argumentsList) {
+    const result = spawnSync(executablePath, argumentsList, {
+        cwd: APP_ROOT,
+        env: process.env,
+        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,38 @@
+'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, '..');
+
+/**
+ * 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'];
+
+    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/prerender-homepage.js

@@ -32,7 +32,7 @@ const SERVER_READY_MARKER = 'Ready in';
 /**
  * Constant for output dir.
  */
-const OUTPUT_DIR = path.join(APP_ROOT, '.next', 'prerendered');
+const OUTPUT_DIR = path.join(APP_ROOT, process.env.NEXT_DIST_DIR || '.next', 'prerendered');
 /**
  * Constant for output file.
  */

package/apps/agents-server/scripts/run-e2e-tests.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const path = require('node:path');
+const { runNpm } = require('./run-npm.js');
+
+/**
+ * Root directory of the Agents Server app.
+ */
+const APP_ROOT = path.resolve(__dirname, '..');
+
+/**
+ * Runs the complete Agents Server E2E verification flow.
+ *
+ * App linting remains an explicit test phase. The production build then skips
+ * its duplicate lint pass, and Playwright starts that same build instead of
+ * compiling a second `.next-e2e` output through `webServer`.
+ */
+function runE2eTests() {
+    const commandOptions = {
+        cwd: APP_ROOT,
+    };
+
+    runNpm(['run', 'lint'], commandOptions);
+    runNpm(['run', 'build-e2e', '--', '--no-lint'], commandOptions);
+
+    runNpm(['exec', '--', 'playwright', 'test', ...process.argv.slice(2)], {
+        ...commandOptions,
+        environmentOverrides: {
+            PTBK_E2E_BUILD_READY: 'true',
+        },
+    });
+}
+
+runE2eTests();

package/apps/agents-server/scripts/run-npm.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+
+/**
+ * Platform-specific npm executable.
+ */
+const NPM_EXECUTABLE = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+/**
+ * Runs one npm command and forwards its output and exit status.
+ *
+ * Windows resolves npm through a `.cmd` shim, which needs shell execution when spawned from
+ * Node.js on some supported Node versions.
+ *
+ * @param {ReadonlyArray<string>} argumentsList - Arguments passed to npm.
+ * @param {{ cwd: string, environmentOverrides?: Readonly<Record<string, string>> }} options - Command options.
+ */
+function runNpm(argumentsList, { cwd, environmentOverrides = {} }) {
+    const result = spawnSync(NPM_EXECUTABLE, argumentsList, {
+        cwd,
+        env: {
+            ...process.env,
+            ...environmentOverrides,
+        },
+        shell: process.platform === 'win32',
+        stdio: 'inherit',
+    });
+
+    if (result.error) {
+        console.error(`Failed to run ${NPM_EXECUTABLE}:`, result.error);
+        process.exit(1);
+    }
+
+    if (result.status !== 0) {
+        process.exit(result.status ?? 1);
+    }
+}
+
+module.exports = {
+    runNpm,
+};

package/apps/agents-server/src/app/admin/email-server/page.tsx

@@ -27,7 +27,7 @@ export default async function AdminEmailServerPage() {
 
     const server = await $provideServer();
     const snapshot = await readStalwartEmailSnapshot(server.publicUrl.hostname);
-    const dnsInstructions = createEmailDnsInstructions(snapshot.domain);
+    const dnsInstructions = createEmailDnsInstructions(snapshot.domain, snapshot.mailDnsDiagnostic.publicIpAddress);
     const isOperational = isStalwartEmailSnapshotOperational(snapshot);
 
     return (
@@ -55,7 +55,8 @@ export default async function AdminEmailServerPage() {
                                     Domain <code>{snapshot.domain}</code> · API{' '}
                                     {snapshot.isReachable ? 'reachable' : 'unavailable'} · bridge{' '}
                                     {snapshot.isBridgeAccountConfigured ? 'configured' : 'missing'} · inbound hook{' '}
-                                    {snapshot.isInboundHookConfigured ? 'configured' : 'missing'}
+                                    {snapshot.isInboundHookConfigured ? 'configured' : 'missing'} · public mail DNS{' '}
+                                    {snapshot.mailDnsDiagnostic.status === 'verified' ? 'verified' : 'needs attention'}
                                 </p>
                                 {snapshot.errorMessage ? (
                                     <p className="mt-2 max-w-4xl whitespace-pre-wrap text-xs">
@@ -110,10 +111,17 @@ export default async function AdminEmailServerPage() {
                     <div className="mt-4">
                         <DnsRecordsInstructions
                             description={
-                                <p>
-                                    Add these records at your DNS provider. Replace <code>&lt;VPS_PUBLIC_IP&gt;</code>{' '}
-                                    with the public address of this VPS.
-                                </p>
+                                snapshot.mailDnsDiagnostic.publicIpAddress ? (
+                                    <p>
+                                        Add these records at your DNS provider. The A records below use this VPS’s
+                                        detected public address.
+                                    </p>
+                                ) : (
+                                    <p>
+                                        Add these records at your DNS provider. Replace <code>&lt;VPS_PUBLIC_IP&gt;</code>{' '}
+                                        with the public address of this VPS.
+                                    </p>
+                                )
                             }
                             domain={snapshot.domain}
                             recordSelection="all"

package/apps/agents-server/src/app/api/elevenlabs/tts/route.ts

@@ -31,7 +31,7 @@ const ELEVEN_LABS_MODEL_ID = process.env.ELEVEN_LABS_MODEL_ID ?? 'eleven_multili
  *
  * @private
  */
-const ELEVEN_LABS_API_KEY = process.env.ELEVEN_LABS_API_KEY;
+const ELEVENLABS_API_KEY = process.env.ELEVENLABS_API_KEY;
 
 /**
  * Maximum number of characters that are sent to a single ElevenLabs TTS request.
@@ -89,7 +89,7 @@ export async function POST(request: NextRequest) {
         });
     }
 
-    if (!ELEVEN_LABS_API_KEY) {
+    if (!ELEVENLABS_API_KEY) {
         return new Response(
             JSON.stringify({
                 error: 'ElevenLabs API key is not configured on the server.',
@@ -153,7 +153,7 @@ export async function POST(request: NextRequest) {
         method: 'POST',
         headers: {
             'Content-Type': 'application/json',
-            'xi-api-key': ELEVEN_LABS_API_KEY,
+            'xi-api-key': ELEVENLABS_API_KEY,
         },
         body: JSON.stringify({
             text: limitedText,

package/apps/agents-server/src/app/api/onboarding/book/route.ts

@@ -1,21 +1,22 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { convertManGoDraftToBook } from '@/src/utils/manGoOnboarding/manGoOnboardingAgentRuntime';
+import { generateManGoBook } from '@/src/utils/manGoOnboarding/manGoOnboardingAgentRuntime';
 import { createManGoOnboardingApiErrorResponse } from '@/src/utils/manGoOnboarding/manGoOnboardingApiResponses';
 import { readManGoOnboardingStringProperty } from '@/src/utils/manGoOnboarding/manGoOnboardingApiRequest';
 
 /**
  * Handles `POST /api/onboarding/book`.
  *
- * @param request - Incoming request with the editable draft input.
- * @returns Canonical Book-language source and validation flag.
+ * @param request - Incoming request with `agentName` and `agentBrief`.
+ * @returns Generated Book-language source.
  */
 export async function POST(request: NextRequest) {
     try {
         const body = await request.json();
-        const input = readManGoOnboardingStringProperty(body, 'input');
-        const result = await convertManGoDraftToBook({ input });
+        const agentName = readManGoOnboardingStringProperty(body, 'agentName');
+        const agentBrief = readManGoOnboardingStringProperty(body, 'agentBrief');
+        const book = await generateManGoBook({ agentName, agentBrief });
 
-        return NextResponse.json(result);
+        return NextResponse.json({ book });
     } catch (error) {
         return createManGoOnboardingApiErrorResponse(error);
     }

package/apps/agents-server/src/app/layout.tsx

@@ -4,6 +4,7 @@ import { createThemeModeBootstrapScript } from '@/src/components/ThemeMode/creat
 import { APPLICATION_FONT_VARIABLE_CLASS_NAME } from '@/src/utils/applicationFonts';
 import type { Metadata } from 'next';
 import { cookies, headers } from 'next/headers';
+import { connection } from 'next/server';
 import { CONTENT_SECURITY_POLICY_NONCE_REQUEST_HEADER } from '../middleware/contentSecurityPolicy';
 import { getCustomJavascriptWithIntegrations } from '../database/customJavascript';
 import { getAggregatedCustomStylesheetCss } from '../database/customStylesheet';
@@ -349,6 +350,11 @@ export default async function RootLayout({
 }: Readonly<{
     children: React.ReactNode;
 }>) {
+    // Every page uses this request-aware layout (cookies, headers, and the current user). Tell Next.js before
+    // starting its database-backed work so a production build does not repeat that work for every static-render
+    // attempt only to discover that the route must be dynamic.
+    await connection();
+
     const layoutMetadataPromise = getMetadataMap([
         'SERVER_NAME',
         'SERVER_LOGO_URL',