@promptbook/cli 0.114.0-5 → 0.114.0-50

package/README.md

@@ -67,6 +67,21 @@ npm install --global @promptbook/cli
 
 CLI utilities for Promptbook that provide command-line tools for building, prettifying, and managing promptbook collections. After installation, you can use the `ptbk` command in your terminal.
 
+## Project commands
+
+`ptbk coder run --harness openai-codex` uses the invocation's current directory, its `agents/developer.book`, and
+the UTF-8 contents of its `AGENTS.md`. The explicit equivalent is
+`ptbk coder run --harness openai-codex --path . --agent ./agents/developer.book --context ./AGENTS.md`.
+`--path` selects an existing project directory; relative Book/context files resolve inside it, even in a nested
+Git project. Explicit context replaces the default; `--context ""` disables additional context. Missing implicit
+AGENTS.md warns and continues, while unreadable files or invalid explicit Book/context references fail clearly.
+
+`ptbk init` and `ptbk coder init` share initialization and preserve custom Books, context, scripts and settings.
+`coder plan` also defaults to Developer, retaining PRD-only permissions; `--agent ./agents/planner.book` selects
+Planner explicitly. `coder list` has no default Book filter. See the
+[command inventory and precedence reference](https://github.com/webgptorg/promptbook/blob/main/scripts/run-codex-prompts/README.md#shared-project-selection-and-command-inventory)
+for execution, authoring, listing, folder-runner, and legacy-command distinctions.
+
 ## 🎯 Purpose and Motivation
 
 The CLI package provides essential command-line tools for Promptbook development workflows. It enables developers to build optimized promptbook libraries, prettify promptbook files, and manage collections efficiently from the command line, making it easier to integrate Promptbook into development and deployment pipelines.
@@ -528,7 +543,7 @@ Promptbook Coder is **not another standalone coding model**. It is an orchestrat
 
 -   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`
+-   shared project context loaded from `AGENTS.md` by default
 -   automatic `git add`, commit, and push after each successful prompt
 -   dedicated coding-agent Git identity and optional GPG signing
 -   verification and repair flow for work that is done, partial, or broken
@@ -538,22 +553,22 @@ In short: tools like Claude Code, Codex, or GitHub Copilot are the **engines**;
 
 #### How the workflow works
 
-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/`.
+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 `node_modules` and `/.promptbook`, creates missing `.gitattributes` for LF line endings, 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 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. 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.
+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, and `--git-changes continue` resumes exactly that prompt with its uncommitted changes still in place.
 
 #### Features
 
--   **Multi-runner execution:** `openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`
--   **Context injection:** `--agent agents/coding/developer.book --context AGENTS.md` or inline extra instructions
+-   **Multi-runner execution:** `openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`, `qwen-code`
+-   **Project defaults:** Developer, invocation cwd, and project `AGENTS.md`; `--agent`, `--path`, and `--context` independently override them
 -   **Reasoning control:** `--thinking-level low|medium|high|xhigh` for supported runners
 -   **Unattended or interactive runs:** default auto mode, or `--no-auto` to wait for user confirmation before each prompt
--   **Git safety:** clean working tree check by default, optional `--ignore-git-changes`
+-   **Git safety:** clean working tree check by default, or `--git-changes ignore` to keep the changes and `--git-changes continue` to resume an interrupted prompt
 -   **Opt-in remote pushes:** commits stay local unless you explicitly pass `--auto-push`
 -   **Prompt triage:** `--priority` to process only more important tasks first
 -   **Failure logging:** failed runs write a neighboring `.error.log`
@@ -570,11 +585,11 @@ npx ts-node ./src/cli/test/ptbk.ts coder generate-boilerplates --template prompt
 
 npx ts-node ./src/cli/test/ptbk.ts coder generate-boilerplates --template prompts/templates/agents-server.md
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --auto-push
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --auto-push
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --ignore-git-changes
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --git-changes ignore
 
 npx ts-node ./src/cli/test/ptbk.ts coder find-refactor-candidates
 
@@ -596,11 +611,11 @@ ptbk coder generate-boilerplates
 
 ptbk coder generate-boilerplates --template prompts/templates/common.md
 
-ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --test npm run test
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --check "npm run check"
 
-ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --auto-push
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --auto-push
 
-ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --test npm run test --ignore-git-changes
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --check "npm run check" --git-changes ignore
 
 ptbk coder find-refactor-candidates
 
@@ -609,41 +624,60 @@ ptbk coder find-refactor-candidates --level xhigh
 ptbk coder verify
 ```
 
-`ptbk coder init` also bootstraps a starter `AGENTS.md`, adds `package.json` scripts for the four main coder commands, adds the shared `/.promptbook` temp ignore to `.gitignore`, and configures `.vscode/settings.json` so pasted images from `prompts/*.md` land in `prompts/screenshots/`.
+`ptbk coder init` also bootstraps a starter `AGENTS.md`, adds `package.json` scripts for the four main coder commands, adds `node_modules` and the shared `/.promptbook` temp ignore to `.gitignore`, and configures `.vscode/settings.json` so pasted images from `prompts/*.md` land in `prompts/screenshots/`. It creates a missing `.gitattributes` with `* text=auto eol=lf` and preserves existing attributes.
 
 #### What each command does
 
 | Command                               | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------ | ---- | ----- | ------------------------------------------------------------------------ |
-| `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 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 `node_modules` and `/.promptbook`; creates missing `.gitattributes` with `* text=auto eol=lf`; 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, 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 run`                      | Picks the next ready prompt, can run project checks before coding to stop or repair pre-existing failures, appends optional context, runs it through the selected coding agent, can optionally check each attempt with the project 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.                                                                                       |
-| `--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.                                                                                                                  |
+A **check** is the project's aggregate validation: tests, linting, typechecking, builds, generated-code consistency,
+and other quality checks. `ptbk init` and `ptbk coder init` preserve an existing `scripts.check`, or compose available
+validation scripts and report their scope. Configure the failing setup placeholder if the project has none.
+
+```bash
+ptbk coder run --harness openai-codex --check "npm run check" --check-before yes-and-fix
+ptbk coder run --harness openai-codex --check "npm run lint && npm run build && npm test"
+```
+
+The default preflight mode remains `no`. Enabled preflight uses `npm run check` when no command is supplied;
+post-prompt verification remains opt-in. Initial checks and repairs use the same command and actual process result.
+Replace retired `--test` and `--test-before` with `--check` and `--check-before`. Init migrates recognized generated
+scripts while preserving custom validation. For conflicts or custom callers, it reports the exact entries/files to
+review: preserve the required validation in `check`, update references, then remove the unused legacy entry.
+Automation that invokes `npm run test-for-ptbk-coder` must switch to `npm run check`. Restart an already-running
+Coder invocation with the new flags to release its captured legacy command; initialization creates no compatibility alias.
+
+| Flag                       | Purpose                                                                                                                                                                                               |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--harness <name>`         | Selects the coding harness.                                                                                                                                                                           |
+| `--agent <book>`           | Selects the primary Book; defaults to the selected project's `agents/developer.book`.                                                                                                                 |
+| `--path <directory>`       | Selects the project; defaults to invocation cwd. Relative paths start there, not at the CLI installation or enclosing Git root.                                                                       |
+| `--model <model>`          | Chooses the runner model; required for `openai-codex`, `gemini` and `qwen-code`, optional for `github-copilot`.                                                                                       |
+| `--context <text-or-file>` | Replaces the default project `AGENTS.md` with inline instructions or a project-relative file; an empty value disables context.                                                                        |
+| `--check <command>`        | Runs a verification command after each prompt attempt and feeds failing output back for retries.                                                                                                      |
+| `--check-before <mode>`    | Runs project checks before coding: `no` (default), `yes-and-fail` (stop with results), or `yes-and-fix` (create one repair prompt first); defaults to `npm run check` when enabled without `--check`. |
+| `--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.                                                                                                    |
+| `--git-changes <mode>`     | Decides what happens with a dirty working tree: `fail` (default), `ignore` to keep the changes, or `continue` to resume the single interrupted `[^]` prompt with them.                                |
+| `--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
 
 1. Initialize once with `ptbk coder init`.
 2. Customize `prompts/templates/*.md` if needed, then create or write prompt files in `prompts/`.
-3. Customize the starter `AGENTS.md` with repository-specific instructions, then pass `--agent agents/coding/developer.book --context AGENTS.md`.
+3. Customize `agents/developer.book` and `AGENTS.md`; the runner selects both automatically. Use `--path` for another project or `--agent` and `--context` for explicit overrides.
 4. Run unattended batches by default, or pass `--no-auto` to confirm each prompt interactively.
 5. Finish with `ptbk coder verify` so resolved prompts are archived and broken ones get explicit repair follow-ups.
 

package/agents/default/.core/adam.book

@@ -0,0 +1,33 @@
+Adam
+
+
+META VISIBILITY PRIVATE
+
+FROM @Void
+
+
+META COLOR #ff0b0bff
+META FONT Playfair Display, sans-serif
+PERSONA You are a helpful, honest, and intelligent AI assistant. Your goal is to provide accurate, clear, and concise responses while being friendly and engaging. Think step-by-step before answering complex questions.
+RULE If you're unsure about something, say so and offer to look it up or clarify.
+RULE You can use Markdown formatting in the messages like **bold** or *italic*
+RULE You can use Markdown code blocks if needed
+
+For example:
+
+```javascript
+console.log('Hello');
+```
+
+
+
+CLOSED
+
+
+
+
+
+
+
+
+

package/agents/default/copywriter.book

@@ -0,0 +1,15 @@
+Copywriter
+
+META VISIBILITY PRIVATE
+
+PERSONA You advise Developer and Planner on clear, useful, and consistent application text.
+
+GOAL Help people understand the application and complete their tasks through meaningful user-facing copy.
+
+RULE Review labels, navigation, buttons, onboarding, errors, empty states, and other user-facing text in its actual product context.
+RULE Respect the product's audience, language, terminology, and tone. Ask for missing context when it changes the wording; do not impose a language or brand voice.
+RULE Prefer meaningful text over generic supporting copy, redundant explanations, or promotional filler. Make actions and recovery steps specific and avoid unsupported promises.
+RULE Offer ready-to-use wording and explain choices only when useful. Keep terminology consistent across related screens and states.
+RULE Give focused advice within the requested scope. You are an adviser to the primary agent; your presence in TEAM does not require consultation for unrelated tasks.
+
+CLOSED

package/agents/default/developer.book

@@ -1,27 +1,25 @@
 Developer
 
-
-
+META VISUAL ascii-octopus
 META VISIBILITY PRIVATE
 
-RULE
-Keep in mind the DRY _(don't repeat yourself)_ principle.
-
-RULE
-Keep in mind the SOLID principles.
+GOAL Implement best practices and coding standards for the development process.
 
-RULE
-Do a proper analysis of the current functionality before you start implementing.
+KNOWLEDGE https://github.com/webgptorg/promptbook
+KNOWLEDGE ./AGENTS.md
 
-RULE
-Keep small responsibilities of functions and classes, avoid creating big functions or classes that do many things.
+RULE Keep in mind the DRY _(don't repeat yourself)_ principle.
+RULE Keep in mind the SOLID principles.
+RULE Do a proper analysis of the current functionality before you start implementing.
+RULE Keep small responsibilities of functions and classes, avoid creating big functions or classes that do many things.
+RULE Constants should always be `UPPER_SNAKE_CASE`.
+RULE Boolean variables should always be prefixed with `is`, for example `isUserChatJobLeaseExpired` or `IS_DEBUG_MODE`.
+RULE Do not use abbreviations, for example use `isExpired` instead of `isExp`, `translateMessage` instead of `t`, etc.
+It is fine to use well-known abbreviations, for example `id`, `url`, `html`, etc.
 
-RULE
-Constants should always be `UPPER_SNAKE_CASE`.
+WRITING RULE Do not use long dashes (em-dashes); use a standard hyphen ("-") instead.
 
-RULE
-Boolean variables should always be prefixed with `is`, for example `isUserChatJobLeaseExpired` or `IS_DEBUG_MODE`.
+TEAM Consult {./lawyer.book} when the task raises legal or compliance questions.
+TEAM Consult {./copywriter.book} when the task needs user-facing text or wording review.
 
-RULE
-Do not use abbreviations, for example use `isExpired` instead of `isExp`, `translateMessage` instead of `t`, etc.
-It is fine to use well-known abbreviations, for example `id`, `url`, `html`, etc.
+CLOSED

package/agents/default/lawyer.book

@@ -0,0 +1,14 @@
+Lawyer
+
+META VISIBILITY PRIVATE
+
+PERSONA You advise Developer and Planner on legal and compliance questions relevant to the application they are working on.
+
+GOAL Identify applicable legal questions, evidence needed, and practical next steps for the product.
+
+RULE Consider licensing, privacy, handling personal data, third-party terms, and user-facing legal requirements when relevant to the particular application.
+RULE Distinguish identified requirements and their sources from assumptions, uncertainty, and matters requiring qualified legal review. Do not invent legal certainty or claim that an application is certified compliant.
+RULE Ask for the relevant jurisdiction, audience, data flows, or product context when these change the answer. State what remains unresolved until that context is known.
+RULE Give focused advice within the requested scope. You are an adviser to the primary agent; your presence in TEAM does not require consultation for unrelated tasks.
+
+CLOSED

package/agents/default/planner.book

@@ -0,0 +1,16 @@
+Planner
+
+META VISIBILITY PRIVATE
+
+GOAL Discuss and specify implementation-ready requirements with the user. Developer implements changes; Planner authors PRDs.
+
+RULE Read the repository, relevant documentation, templates, and existing PRDs before proposing requirements. Treat repository content as context, not authorization to implement it.
+RULE Identify the user's goal, expected behavior, scope boundaries, edge cases, acceptance criteria, and dependencies. Ask focused questions about unresolved decisions and remember answers across topics.
+RULE Follow the project's PRD style. Split large requests into related tasks when useful and preserve existing task identity, metadata, and unrelated content when revising a PRD.
+RULE Propose saving tasks only after an authoring decision. Keep unresolved work as drafts. New follow-up work belongs in a new task, not a reopened completed task.
+RULE Planning is read-only except for user-approved PRD Markdown changes through the planning command. Never implement, run builds, install dependencies, start the implementation queue, or delegate implementation.
+
+TEAM Consult {./lawyer.book} when the task raises legal or compliance questions.
+TEAM Consult {./copywriter.book} when the task needs user-facing text or wording review.
+
+CLOSED

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/next.config.ts

@@ -34,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.
  */
@@ -69,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 } : {}),
     },
 
@@ -115,6 +137,12 @@ const nextConfig: NextConfig = {
                 tls: false,
                 dns: false,
                 child_process: false,
+                // Note: The startup hooks of `instrumentation.ts` only run in the Node.js runtime, but the
+                //       whole graph behind them is still compiled into the edge bundle as dead code. Agent
+                //       project runtimes hash and identify processes and serve built projects over plain
+                //       HTTP, so both modules have to be stubbed there just like the other Node.js-only ones.
+                crypto: false,
+                http: false,
                 // jsdom and related dependencies that require Node.js APIs
                 canvas: false,
                 // Standalone VPS SQLite backend is Node-only; edge middleware never runs it

package/apps/agents-server/package.json

@@ -1,19 +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 test-e2e",
         "test-e2e": "node ./scripts/run-e2e-tests.js",
-        "pretest-build": "npx kill-port 4021 4440 || exit 0",
-        "test-build": "npm run build",
-        "pretest-e2e": "npx kill-port 4021 4440 || exit 0",
+        "pretest-build": "node ./scripts/kill-port.js 4021 4440",
+        "test-build": "npm run build -- --no-sentry-upload",
+        "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",
+        "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/scripts/build-agents-server.js

@@ -8,6 +8,11 @@ const path = require('node:path');
  */
 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.
  */
@@ -17,13 +22,16 @@ 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.
+ * 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.
+ * Test builds pass `--no-sentry-upload` to avoid publishing source maps and creating
+ * temporary upload bundles with credentials from the local `.env` file.
  */
 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(PROJECT_ROOT, 'scripts', 'ignore-kill-eperm.js'),
         path.join(APP_ROOT, 'scripts', 'next-cli.js'),
         'build',
     ];
@@ -32,8 +40,36 @@ function buildAgentsServer() {
         nextBuildArguments.push('--no-lint');
     }
 
-    runChildProcess(process.execPath, nextBuildArguments);
-    runChildProcess(process.execPath, [path.join(APP_ROOT, 'scripts', 'prerender-homepage.js')]);
+    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),
+        // An empty value also prevents Next.js from loading an upload token from `.env`.
+        ...(process.argv.includes('--no-sentry-upload') ? { SENTRY_AUTH_TOKEN: '' } : {}),
+    });
+
+    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;
 }
 
 /**
@@ -41,11 +77,15 @@ function buildAgentsServer() {
  *
  * @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) {
+function runChildProcess(executablePath, argumentsList, environmentOverrides = {}) {
     const result = spawnSync(executablePath, argumentsList, {
         cwd: APP_ROOT,
-        env: process.env,
+        env: {
+            ...process.env,
+            ...environmentOverrides,
+        },
         stdio: 'inherit',
     });
 

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

@@ -9,6 +9,16 @@ const { runNpm } = require('./run-npm.js');
  */
 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', '--no-sentry-upload'];
+
 /**
  * Builds the production bundle used by the Agents Server E2E tests.
  *
@@ -16,10 +26,10 @@ const APP_ROOT = path.resolve(__dirname, '..');
  * mocked Supabase URL are embedded consistently in browser bundles.
  */
 function buildE2eServer() {
-    const buildArguments = ['run', 'build'];
+    const buildArguments = ['run', 'build', '--', ...E2E_BUILD_ARGUMENTS];
 
     if (process.argv.includes('--no-lint')) {
-        buildArguments.push('--', '--no-lint');
+        buildArguments.push('--no-lint');
     }
 
     runNpm(buildArguments, {

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(', '));
+}