@promptbook/types 0.114.0-5 → 0.114.0-51

package/README.md

@@ -653,7 +653,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
@@ -663,22 +663,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`
@@ -695,11 +695,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
 
@@ -721,11 +721,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
 
@@ -734,41 +734,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/esm/src/_packages/components.index.d.ts

@@ -70,8 +70,10 @@ import type { CitationLabelResolver } from '../book-components/Chat/types/Citati
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import { parseMessageButtons } from '../book-components/Chat/utils/parseMessageButtons';
 import type { MarkdownInlineReference } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceIcon } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuStatus } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuOption } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceMenuAction } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenu } from '../book-components/Chat/utils/renderMarkdown';
 import { ArrowIcon } from '../book-components/icons/ArrowIcon';
 import { MicIcon } from '../book-components/icons/MicIcon';
@@ -159,8 +161,10 @@ export type { CitationLabelResolver };
 export type { MessageButton };
 export { parseMessageButtons };
 export type { MarkdownInlineReference };
+export type { MarkdownInlineReferenceIcon };
 export type { MarkdownInlineReferenceMenuStatus };
 export type { MarkdownInlineReferenceMenuOption };
+export type { MarkdownInlineReferenceMenuAction };
 export type { MarkdownInlineReferenceMenu };
 export { ArrowIcon };
 export { MicIcon };

package/esm/src/_packages/types.index.d.ts

@@ -62,8 +62,10 @@ import type { CitationLabelResolver } from '../book-components/Chat/types/Citati
 import type { ParsedCitation } from '../book-components/Chat/utils/parseCitationsFromContent';
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import type { MarkdownInlineReference } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceIcon } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuStatus } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuOption } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceMenuAction } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenu } from '../book-components/Chat/utils/renderMarkdown';
 import type { TeamToolResult } from '../book-components/Chat/utils/toolCallParsing/TeamToolResult';
 import type { QrCodeOptions } from '../book-components/Qr/useQrCode';
@@ -511,8 +513,10 @@ export type { CitationLabelResolver };
 export type { ParsedCitation };
 export type { MessageButton };
 export type { MarkdownInlineReference };
+export type { MarkdownInlineReferenceIcon };
 export type { MarkdownInlineReferenceMenuStatus };
 export type { MarkdownInlineReferenceMenuOption };
+export type { MarkdownInlineReferenceMenuAction };
 export type { MarkdownInlineReferenceMenu };
 export type { TeamToolResult };
 export type { QrCodeOptions };

package/esm/src/avatars/renderAvatarVisualTerminalText.d.ts

@@ -0,0 +1,80 @@
+import type { AsciiArtColorDepth } from '../utils/ascii-art/convertImageDataToAsciiArt';
+import type { ResolvedAvatarRenderDefinition } from './renderAvatarVisual';
+import type { AvatarDefinition } from './types/AvatarDefinition';
+import type { AvatarSurfaceStyle, AvatarVisualId, AvatarVisualTerminalTextGrid } from './types/AvatarVisualDefinition';
+/**
+ * Options shared by the terminal-text avatar renderers.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualTerminalTextOptions = {
+    /**
+     * Stable visual identity of the rendered agent avatar.
+     */
+    readonly avatarDefinition: AvatarDefinition;
+    /**
+     * Built-in avatar visual to render, the same one used on the website.
+     */
+    readonly visualId: AvatarVisualId;
+    /**
+     * Surface used to derive the avatar palette.
+     *
+     * @default 'framed'
+     */
+    readonly surface?: AvatarSurfaceStyle;
+    /**
+     * Output width in terminal character cells.
+     */
+    readonly columns: number;
+    /**
+     * Output height in terminal character cells.
+     */
+    readonly rows: number;
+    /**
+     * Animation timestamp for animated visuals.
+     */
+    readonly timeMs: number;
+    /**
+     * Optional stable render data reused across frames.
+     */
+    readonly resolvedAvatarRenderDefinition?: ResolvedAvatarRenderDefinition;
+};
+/**
+ * Options for `renderAvatarVisualTerminalTextLines`.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualTerminalTextLinesOptions = RenderAvatarVisualTerminalTextOptions & {
+    /**
+     * Color depth of the emitted ANSI escape codes.
+     *
+     * @default 'TRUE_COLOR'
+     */
+    readonly colorDepth?: AsciiArtColorDepth;
+};
+/**
+ * Renders one frame of a character-based avatar visual straight into terminal character cells.
+ *
+ * Visuals which are themselves made of characters, for example `AsciiOctopus`, lose their identity
+ * when they are rasterized onto a canvas and converted back into half-block ASCII art - every glyph
+ * is averaged away into a colored blob. Such visuals expose `renderTerminalText`, which paints the
+ * terminal grid directly and is used instead of the raster pipeline.
+ *
+ * The square avatar is centered inside the requested grid the same way `renderAvatarVisualAsciiArt`
+ * centers the avatar canvas inside a wider terminal frame.
+ *
+ * @param options Avatar identity, visual selection, and output grid size.
+ * @returns Grid of `rows` rows of `columns` cells, or `null` when the visual has no terminal renderer.
+ *
+ * @private within the repository
+ */
+export declare function renderAvatarVisualTerminalTextGrid(options: RenderAvatarVisualTerminalTextOptions): AvatarVisualTerminalTextGrid | null;
+/**
+ * Renders one frame of a character-based avatar visual into ANSI-colored terminal lines.
+ *
+ * @param options Avatar identity, visual selection, output grid size, and ANSI color depth.
+ * @returns One ANSI-colored string per output row, or `null` when the visual has no terminal renderer.
+ *
+ * @private within the repository
+ */
+export declare function renderAvatarVisualTerminalTextLines(options: RenderAvatarVisualTerminalTextLinesOptions): ReadonlyArray<string> | null;

package/esm/src/avatars/types/AvatarVisualDefinition.d.ts

@@ -72,6 +72,52 @@ export type AvatarVisualRenderContext = {
  * @private shared contract for the avatar rendering system
  */
 export type AvatarVisual = (context: AvatarVisualRenderContext) => void;
+/**
+ * One painted character cell of a terminal-text avatar frame.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextCell = {
+    /**
+     * Single character painted in the cell.
+     */
+    readonly character: string;
+    /**
+     * Color of the character as a CSS color string, optionally with an alpha channel.
+     */
+    readonly color: string_color;
+};
+/**
+ * One rendered terminal-text avatar frame as a grid of character cells.
+ *
+ * Rows are ordered top to bottom, cells left to right, and `null` leaves the terminal background visible.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextGrid = ReadonlyArray<ReadonlyArray<AvatarVisualTerminalTextCell | null>>;
+/**
+ * Rendering context forwarded to a terminal-text avatar visual.
+ *
+ * Unlike `AvatarVisualRenderContext` this carries no canvas, because the visual paints
+ * character cells of a fixed terminal grid instead of pixels.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextRenderContext = {
+    readonly columns: number;
+    readonly rows: number;
+    readonly timeMs: number;
+    readonly avatarDefinition: AvatarDefinition;
+    readonly palette: AvatarPalette;
+    readonly createRandom: (salt: string) => () => number;
+    readonly interaction: AvatarInteractionState;
+};
+/**
+ * Signature of one terminal-text avatar visual renderer.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalText = (context: AvatarVisualTerminalTextRenderContext) => AvatarVisualTerminalTextGrid;
 /**
  * Metadata and renderer for one built-in avatar visual.
  *
@@ -84,6 +130,14 @@ export type AvatarVisualDefinition = {
     readonly isAnimated: boolean;
     readonly supportsPointerTracking?: boolean;
     readonly render: AvatarVisual;
+    /**
+     * Optional native terminal renderer of visuals which are themselves made of characters.
+     *
+     * Character-based visuals lose their identity when they are rasterized onto a canvas and
+     * converted back into half-block ASCII art, so they paint the terminal character grid directly.
+     * Visuals without this renderer are rasterized through `renderAvatarVisualAsciiArt` instead.
+     */
+    readonly renderTerminalText?: AvatarVisualTerminalText;
 };
 /**
  * Props of the shared `<Avatar/>` component.

package/esm/src/book-2.0/agent-source/AgentReferenceResolutionIssue.d.ts

@@ -0,0 +1,45 @@
+import type { BookCommitment } from '../../commitments/_base/BookCommitment';
+import type { AgentReferenceResolver } from './AgentReferenceResolver';
+/**
+ * Structured issue captured when compact agent reference resolution fails.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export type AgentReferenceResolutionIssue = {
+    /**
+     * Commitment where the unresolved token appeared.
+     */
+    readonly commitmentType: BookCommitment;
+    /**
+     * Original token text (for example `{Unknown Agent}` or `@UnknownAgent`).
+     */
+    readonly token: string;
+    /**
+     * Normalized token payload used for lookup.
+     */
+    readonly reference: string;
+    /**
+     * Human-readable explanation of why the token could not be resolved.
+     */
+    readonly message: string;
+};
+/**
+ * Extension implemented by resolvers that can expose accumulated resolution issues.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export type IssueTrackingAgentReferenceResolver = AgentReferenceResolver & {
+    /**
+     * Returns tracked issues and clears the internal queue.
+     */
+    consumeResolutionIssues(): Array<AgentReferenceResolutionIssue>;
+};
+/**
+ * Drains unresolved compact-reference issues from a resolver when supported.
+ *
+ * @param resolver - Resolver instance that may implement issue tracking.
+ * @returns Collected issues or an empty list.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export declare function consumeAgentReferenceResolutionIssues(resolver?: AgentReferenceResolver): Array<AgentReferenceResolutionIssue>;

package/esm/src/book-2.0/agent-source/AgentSourceParseResult.d.ts

@@ -1,5 +1,6 @@
 import type { ParsedCommitment } from '../../commitments/_base/ParsedCommitment';
 import type { string_agent_name } from '../../types/string_agent_name';
+import type { ParsedUnknownCommitment } from './ParsedUnknownCommitment';
 /**
  * Result of parsing agent source for commitments
  *
@@ -18,6 +19,10 @@ export type AgentSourceParseResult = {
      * All parsed commitments
      */
     commitments: ParsedCommitment[];
+    /**
+     * Uppercase commitment blocks whose types are not registered by Promptbook.
+     */
+    unknownCommitments: ParsedUnknownCommitment[];
     /**
      * Lines that are not commitments (for system message)
      */

package/esm/src/book-2.0/agent-source/CreateAgentModelRequirementsOptions.d.ts

@@ -7,6 +7,8 @@ import type { TeammateProfileResolver } from './TeammateProfileResolver';
  * @public exported from `@promptbook/core`
  */
 export type CreateAgentModelRequirementsOptions = {
+    /** A host supplying its own scoped TEAM runtime only needs the tool definitions, not global executors. */
+    readonly isTeamToolRegistrationDisabled?: boolean;
     /**
      * Resolver that transforms compact agent references (FROM, IMPORT, TEAM) into concrete URLs.
      */

package/esm/src/book-2.0/agent-source/ParsedUnknownCommitment.d.ts

@@ -0,0 +1,26 @@
+/**
+ * An uppercase Book commitment block whose keyword is not registered by Promptbook.
+ *
+ * Unknown commitments are retained as system-message context instead of being applied
+ * as executable commitments.
+ *
+ * @private internal type of `parseAgentSourceWithCommitments`
+ */
+export type ParsedUnknownCommitment = {
+    /**
+     * Uppercase unknown commitment type, for example `FOO` or `BAR BZZ`.
+     */
+    readonly type: string;
+    /**
+     * Original first line, retained for precise editor diagnostics.
+     */
+    readonly originalLine: string;
+    /**
+     * Line number in the agent source (1-based).
+     */
+    readonly lineNumber: number;
+    /**
+     * Complete unknown commitment block, including its keyword and continuation lines.
+     */
+    readonly source: string;
+};

package/esm/src/book-2.0/agent-source/deduplicateSystemMessage.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Removes duplicated instructions from a generated system message
+ *
+ * Commitments are applied one by one, so a commitment used multiple times in one book repeats its whole
+ * section, including the shared guidance preamble. For example two `WRITING RULES` commitments emit the
+ * `## Writing rules` heading and its guidance paragraph twice. This function merges all sections sharing
+ * one heading into the position of their first occurrence and keeps every identical block only once.
+ *
+ * @param systemMessage The assembled system message which may contain repeated sections and blocks
+ * @returns The system message where each section heading and each identical block appears exactly once
+ *
+ * @private internal utility of `createAgentModelRequirementsWithCommitments`
+ */
+export declare function deduplicateSystemMessage(systemMessage: string): string;

package/esm/src/book-2.0/agent-source/explicitFromCommitment.d.ts

@@ -0,0 +1,62 @@
+import type { string_book } from './string_book';
+/**
+ * One explicit `FROM` commitment written in a book.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export type ExplicitFromCommitment = {
+    /**
+     * Zero-based index of the line the commitment was found on, within the scanned lines.
+     */
+    readonly lineIndex: number;
+    /**
+     * Trimmed commitment content, empty string for a blank `FROM`.
+     */
+    readonly content: string;
+};
+/**
+ * Collects every explicit single-line `FROM` commitment of one book.
+ *
+ * This lightweight parser is intentionally limited to the subset needed by inheritance
+ * resolution so it stays safe to bundle into the Next.js proxy path.
+ *
+ * @param sourceLines - Book source already split into lines.
+ * @returns Found `FROM` commitments in source order, empty when the book declares no parent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export declare function collectExplicitFromCommitments(sourceLines: ReadonlyArray<string>): ReadonlyArray<ExplicitFromCommitment>;
+/**
+ * Returns the effective explicit `FROM` commitment of one book.
+ *
+ * A book may repeat `FROM`, in which case the last one wins and overrides every earlier one.
+ *
+ * @param agentSource - Raw book source.
+ * @returns The last explicit `FROM` commitment, or `undefined` when the book declares no parent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export declare function getEffectiveExplicitFromCommitment(agentSource: string_book): ExplicitFromCommitment | undefined;
+/**
+ * Returns the effective explicit `FROM` commitment content of one book.
+ *
+ * A book may repeat `FROM`, in which case the last one wins and overrides every earlier one.
+ *
+ * @param agentSource - Raw book source.
+ * @returns Trimmed commitment content, empty string for a blank explicit `FROM`, or `undefined` when `FROM` is absent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export declare function getExplicitFromCommitmentContent(agentSource: string_book): string | undefined;
+/**
+ * Returns true when one book declares no parent at all and therefore implicitly inherits from `@Adam`.
+ *
+ * Writing no `FROM` commitment is equivalent to writing `FROM @Adam`, so only an explicit
+ * `FROM @Null` / `FROM {Void}` turns the inheritance off.
+ *
+ * @param agentSource - Raw book source.
+ * @returns True when the implicit `@Adam` ancestor applies to this book.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export declare function isImplicitAdamInheritance(agentSource: string_book): boolean;

package/esm/src/book-2.0/agent-source/extractAgentReferenceTokens.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Matched compact agent reference token inside commitment content.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export type AgentReferenceTokenMatch = {
+    /**
+     * Original token text, for example `{Agent Name}` or `@AgentId`.
+     */
+    readonly token: string;
+    /**
+     * Token payload used for lookup.
+     */
+    readonly reference: string;
+    /**
+     * Zero-based character offset of `token` in the scanned content.
+     */
+    readonly index: number;
+    /**
+     * Length of `token` in characters.
+     */
+    readonly length: number;
+};
+/**
+ * Extracts compact agent-reference tokens from commitment content.
+ *
+ * @param content - Commitment content to inspect.
+ * @returns Matched compact reference tokens.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export declare function extractAgentReferenceTokens(content: string): Array<AgentReferenceTokenMatch>;

package/esm/src/book-2.0/agent-source/getBookCommitmentLineType.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Creates the regex used to recognize the uppercase commitment type at the beginning of a Book line.
+ *
+ * A fresh regular expression keeps Monaco tokenizer state isolated from parser calls.
+ *
+ * @returns Regular expression matching one Book commitment-like line.
+ *
+ * @private internal utility of Book parsing and `<BookEditor/>`
+ */
+export declare function createBookCommitmentLineTypeRegex(): RegExp;
+/**
+ * Extracts the uppercase commitment type from a Book line, including types not registered by Promptbook.
+ *
+ * @param line - One raw Book source line.
+ * @returns Matched commitment type or `null` when the line does not begin with commitment syntax.
+ *
+ * @private internal utility of Book parsing and `<BookEditor/>`
+ */
+export declare function getBookCommitmentLineType(line: string): string | null;

package/esm/src/book-2.0/agent-source/parseAgentSourceWithCommitments.unknown.test.d.ts

@@ -0,0 +1 @@
+export {};