@promptbook/markdown-utils 0.114.0-25 → 0.114.0-27

package/esm/index.es.js

@@ -22,7 +22,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-25';
+const PROMPTBOOK_ENGINE_VERSION = '0.114.0-27';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name

package/esm/src/cli/cli-commands/common/harness/$applyHarnessInstallationStatus.d.ts

@@ -2,7 +2,7 @@ import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
 /**
  * Reports one detected harness installation status and offers to install or update the harness.
  *
- * Note: `$` is used to indicate that this function is not a pure function - it asks the user and installs npm packages
+ * Note: `$` is used to indicate that this function is not a pure function - it asks the user and installs software
  *
  * @private internal utility of `promptbookCli`
  */

package/esm/src/cli/cli-commands/common/harness/$resolveHarnessCommandPath.d.ts

@@ -0,0 +1,14 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+/**
+ * Finds out which file is really executed when the harness command runs.
+ *
+ * The lookup deliberately uses the very same `PATH` which runs the harness, so it reports the copy of the
+ * harness which Promptbook itself would use. Symbolic links are followed, because installers like the
+ * standalone OpenAI Codex installer only link their package into a directory on `PATH`.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs a command in a shell
+ *
+ * @returns Resolved path of the harness command or `null` when the command is not available
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $resolveHarnessCommandPath(definition: HarnessDefinition): Promise<string | null>;

package/esm/src/cli/cli-commands/common/harness/$resolveHarnessInstallationOrigin.d.ts

@@ -0,0 +1,10 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationOrigin } from './HarnessInstallationOrigin';
+/**
+ * Finds out where one CLI coding harness is really installed and which tool manages it.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs shell commands
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $resolveHarnessInstallationOrigin(definition: HarnessDefinition): Promise<HarnessInstallationOrigin>;

package/esm/src/cli/cli-commands/common/harness/$runHarnessInstallationCommand.d.ts

@@ -0,0 +1,43 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+/**
+ * What one harness installation command does with the harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationOperation = 'install' | 'update';
+/**
+ * Options of one command which installs or updates a CLI coding harness.
+ *
+ * @private internal utility of `$runHarnessInstallationCommand`
+ */
+type HarnessInstallationCommandOptions = {
+    /**
+     * Harness which is installed or updated.
+     */
+    readonly definition: HarnessDefinition;
+    /**
+     * What the command does with the harness.
+     */
+    readonly operation: HarnessInstallationOperation;
+    /**
+     * Shell command which does it.
+     */
+    readonly command: string;
+    /**
+     * Extra environment variables required by the command.
+     */
+    readonly environment?: Readonly<Record<string, string>>;
+};
+/**
+ * Runs one command which installs or updates a CLI coding harness.
+ *
+ * A failed installation is reported but never aborts the running command, because the harness check
+ * is only an assistant - the command itself may still work with a manually managed harness.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it installs software
+ *
+ * @returns `true` when the command succeeded, `false` when it failed
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $runHarnessInstallationCommand(options: HarnessInstallationCommandOptions): Promise<boolean>;
+export {};

package/esm/src/cli/cli-commands/common/harness/HarnessDefinition.d.ts

@@ -1,4 +1,24 @@
 import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
+/**
+ * Description of a standalone *(self-managed)* installation of one CLI coding harness.
+ *
+ * Some harnesses are also distributed by their own installer which puts the harness outside of npm and
+ * updates it in place. Such an installation must never be updated with `npm install -g`, because that
+ * installs a second copy of the harness instead of updating the one which is really used.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessStandaloneInstallation = {
+    /**
+     * Directory names which appear in the resolved path of a standalone installation of the harness,
+     * for example `.codex` in `~/.codex/packages/standalone/current/bin/codex`.
+     */
+    readonly directoryNames: ReadonlyArray<string>;
+    /**
+     * Command which updates the standalone installation in place.
+     */
+    readonly updateCommand: string;
+};
 /**
  * Static description of one supported CLI coding harness.
  *
@@ -25,6 +45,12 @@ export type HarnessDefinition = {
      * Extra environment variables required by the global npm installation of this harness.
      */
     readonly npmInstallEnvironment?: Readonly<Record<string, string>>;
+    /**
+     * How a standalone installation of this harness is recognized and updated.
+     *
+     * Harnesses which are distributed only through npm leave this undefined.
+     */
+    readonly standaloneInstallation?: HarnessStandaloneInstallation;
 };
 /**
  * Single source of truth about how each supported CLI coding harness is installed and detected.

package/esm/src/cli/cli-commands/common/harness/HarnessInstallationOrigin.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Way in which the globally available harness command got onto the current machine.
+ *
+ * - `npm-global` the command comes from a global npm installation, so `npm install -g` really updates it
+ * - `standalone` the command was installed by the own installer of the harness and updates itself in place
+ * - `homebrew` the command is managed by Homebrew, so only `brew` may update it
+ * - `unknown` the command lives somewhere else or could not be located at all
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationMethod = 'npm-global' | 'standalone' | 'homebrew' | 'unknown';
+/**
+ * Place where the harness command really lives together with the way it was installed there.
+ *
+ * Knowing the origin is what keeps an update from installing a **second** copy of a harness which is
+ * managed outside of npm, for example the standalone installation of OpenAI Codex.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationOrigin = {
+    /**
+     * Resolved path of the harness command with every symbolic link followed
+     * or `null` when the command could not be located.
+     */
+    readonly commandPath: string | null;
+    /**
+     * Way in which the harness command was installed.
+     */
+    readonly installationMethod: HarnessInstallationMethod;
+};
+/**
+ * Origin used when the harness command was not looked up at all, for example when the update check is disabled.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const UNKNOWN_HARNESS_INSTALLATION_ORIGIN: HarnessInstallationOrigin;

package/esm/src/cli/cli-commands/common/harness/HarnessInstallationStatus.d.ts

@@ -1,4 +1,5 @@
 import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationOrigin } from './HarnessInstallationOrigin';
 /**
  * Result of comparing the globally installed harness version with the newest published one.
  *
@@ -33,4 +34,8 @@ export type HarnessInstallationStatus = {
      * Newest version published to npm or `null` when it could not be resolved.
      */
     readonly latestVersion: string | null;
+    /**
+     * Place where the harness command lives together with the way it was installed there.
+     */
+    readonly installationOrigin: HarnessInstallationOrigin;
 };

package/esm/src/cli/cli-commands/common/harness/HarnessUpdatePlan.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How an outdated CLI coding harness can be brought up to date where it is really installed.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessUpdatePlan = {
+    /**
+     * Command which updates the harness in place
+     * or `null` when the installation is not understood well enough to name one.
+     */
+    readonly command: string | null;
+    /**
+     * Whether Promptbook may run the command itself instead of only printing it.
+     *
+     * Only installations which Promptbook can update without any side effect are updated automatically,
+     * everything else is left to the user together with the instructions.
+     */
+    readonly isRunnableByPromptbook: boolean;
+    /**
+     * Extra environment variables required by the update command.
+     */
+    readonly environment?: Readonly<Record<string, string>>;
+};

package/esm/src/cli/cli-commands/common/harness/buildHarnessInstallCommand.d.ts

@@ -2,9 +2,12 @@ import type { HarnessDefinition } from './HarnessDefinition';
 /**
  * Builds the shell command which installs or updates one CLI coding harness globally.
  *
- * The very same command is executed by `$installHarness` and printed as the manual fallback,
+ * The very same command is executed by `$runHarnessInstallationCommand` and printed as the manual fallback,
  * so the user always sees exactly what Promptbook would run.
  *
+ * Note: This command installs the harness through npm, so it may only update a harness which npm really owns,
+ * see `resolveHarnessUpdatePlan`.
+ *
  * @private internal utility of `promptbookCli`
  */
 export declare function buildHarnessInstallCommand(definition: HarnessDefinition): string;

package/esm/src/cli/cli-commands/common/harness/formatHarnessManualUpdateInstruction.d.ts

@@ -0,0 +1,8 @@
+import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
+import type { HarnessUpdatePlan } from './HarnessUpdatePlan';
+/**
+ * Formats the instruction shown when an outdated harness must be updated by the user.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function formatHarnessManualUpdateInstruction(status: HarnessInstallationStatus, updatePlan: HarnessUpdatePlan): string;

package/esm/src/cli/cli-commands/common/harness/formatHarnessManualUpdateInstruction.test.d.ts

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

package/esm/src/cli/cli-commands/common/harness/resolveHarnessInstallationMethodFromPaths.d.ts

@@ -0,0 +1,31 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationMethod } from './HarnessInstallationOrigin';
+/**
+ * Options describing where the harness command was found.
+ *
+ * @private internal utility of `resolveHarnessInstallationMethodFromPaths`
+ */
+type HarnessInstallationPaths = {
+    /**
+     * Harness whose command was located.
+     */
+    readonly definition: HarnessDefinition;
+    /**
+     * Resolved path of the harness command with every symbolic link followed.
+     */
+    readonly commandPath: string;
+    /**
+     * Root directory of global npm installations or `null` when npm could not be asked for it.
+     */
+    readonly npmGlobalPrefixPath: string | null;
+};
+/**
+ * Decides how a harness command was installed from the place where it really lives.
+ *
+ * Only a command which npm owns may be updated with `npm install -g`, every other command has to be
+ * updated where it is installed, otherwise the update silently adds a second copy of the harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function resolveHarnessInstallationMethodFromPaths(paths: HarnessInstallationPaths): HarnessInstallationMethod;
+export {};

package/esm/src/cli/cli-commands/common/harness/resolveHarnessInstallationMethodFromPaths.test.d.ts

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

package/esm/src/cli/cli-commands/common/harness/resolveHarnessUpdatePlan.d.ts

@@ -0,0 +1,12 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationMethod } from './HarnessInstallationOrigin';
+import type { HarnessUpdatePlan } from './HarnessUpdatePlan';
+/**
+ * Decides how one outdated CLI coding harness should be updated.
+ *
+ * The plan follows the way the harness was installed, because `npm install -g` updates only a harness
+ * which npm owns and installs a **second** copy of every other one.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function resolveHarnessUpdatePlan(definition: HarnessDefinition, installationMethod: HarnessInstallationMethod): HarnessUpdatePlan;

package/esm/src/cli/cli-commands/common/harness/resolveHarnessUpdatePlan.test.d.ts

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

package/esm/src/cli/cli-commands/common/npm/$resolveNpmGlobalPrefixPath.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reads the root directory under which npm installs global packages.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs npm
+ *
+ * @returns The global npm prefix or `null` when npm could not be asked for it
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $resolveNpmGlobalPrefixPath(): Promise<string | null>;

package/esm/src/commitments/WRITING_RULES/WRITING_RULES.d.ts

@@ -3,23 +3,30 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
 /**
  * `WRITING RULES` commitment definition.
  *
- * It adds constraints that apply strictly to writing style and presentation
- * rather than task-solving behavior.
+ * The `WRITING RULES`/`WRITING RULE` commitment adds constraints that apply strictly to writing style
+ * and presentation rather than task-solving behavior.
+ *
+ * Example usage in agent source:
+ *
+ * ```book
+ * WRITING RULES Keep every response under 120 words
+ * WRITING RULE Always end the message with an emoji
+ * ```
  *
  * @private [🪔] Maybe export the commitments through some package
  */
-export declare class WritingRulesCommitmentDefinition extends BaseCommitmentDefinition<'WRITING RULES'> {
-    constructor();
+export declare class WritingRulesCommitmentDefinition extends BaseCommitmentDefinition<'WRITING RULES' | 'WRITING RULE'> {
+    constructor(type?: 'WRITING RULES' | 'WRITING RULE');
     /**
-     * Short one-line description of `WRITING RULES`.
+     * Short one-line description of `WRITING RULES`/`WRITING RULE`.
      */
     get description(): string;
     /**
-     * Icon for `WRITING RULES`.
+     * Icon for `WRITING RULES`/`WRITING RULE`.
      */
     get icon(): string;
     /**
-     * Markdown documentation for `WRITING RULES`.
+     * Markdown documentation for `WRITING RULES`/`WRITING RULE` commitment.
      */
     get documentation(): string;
     applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements;

package/esm/src/commitments/index.d.ts

@@ -55,4 +55,4 @@ import { NotYetImplementedCommitmentDefinition } from './_base/NotYetImplemented
  *
  * @private Use functions to access commitments instead of this array directly
  */
-export declare const COMMITMENT_REGISTRY: readonly [PersonaCommitmentDefinition, PersonaCommitmentDefinition, KnowledgeCommitmentDefinition, StyleCommitmentDefinition, StyleCommitmentDefinition, RuleCommitmentDefinition, RuleCommitmentDefinition, LanguageCommitmentDefinition, LanguageCommitmentDefinition, WritingSampleCommitmentDefinition, WritingRulesCommitmentDefinition, SampleCommitmentDefinition, SampleCommitmentDefinition, FormatCommitmentDefinition, FormatCommitmentDefinition, TemplateCommitmentDefinition, TemplateCommitmentDefinition, FromCommitmentDefinition, ImportCommitmentDefinition, ImportCommitmentDefinition, ModelCommitmentDefinition, ModelCommitmentDefinition, ActionCommitmentDefinition, ActionCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaImageCommitmentDefinition, MetaColorCommitmentDefinition, MetaFontCommitmentDefinition, MetaLinkCommitmentDefinition, MetaDomainCommitmentDefinition, MetaDescriptionCommitmentDefinition, MetaDisclaimerCommitmentDefinition, MetaFullnameCommitmentDefinition, MetaIdCommitmentDefinition, MetaInputPlaceholderCommitmentDefinition, MetaThinkingMessageCommitmentDefinition, MetaVisibilityCommitmentDefinition, MetaVoiceCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, GoalCommitmentDefinition, GoalCommitmentDefinition, InitialMessageCommitmentDefinition, UserMessageCommitmentDefinition, InternalMessageCommitmentDefinition, AgentMessageCommitmentDefinition, MessageSuffixCommitmentDefinition, MessageCommitmentDefinition, MessageCommitmentDefinition, ScenarioCommitmentDefinition, ScenarioCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DictionaryCommitmentDefinition, OpenCommitmentDefinition, ClosedCommitmentDefinition, TeamCommitmentDefinition, UseUserLocationCommitmentDefinition, UseCalendarCommitmentDefinition, UsePopupCommitmentDefinition, UseImageGeneratorCommitmentDefinition, UseMcpCommitmentDefinition, UsePrivacyCommitmentDefinition, UseProjectCommitmentDefinition, NotYetImplementedCommitmentDefinition<"EXPECT">, NotYetImplementedCommitmentDefinition<"BEHAVIOUR">, NotYetImplementedCommitmentDefinition<"BEHAVIOURS">, NotYetImplementedCommitmentDefinition<"AVOID">, NotYetImplementedCommitmentDefinition<"AVOIDANCE">, NotYetImplementedCommitmentDefinition<"CONTEXT">];
+export declare const COMMITMENT_REGISTRY: readonly [PersonaCommitmentDefinition, PersonaCommitmentDefinition, KnowledgeCommitmentDefinition, StyleCommitmentDefinition, StyleCommitmentDefinition, RuleCommitmentDefinition, RuleCommitmentDefinition, LanguageCommitmentDefinition, LanguageCommitmentDefinition, WritingSampleCommitmentDefinition, WritingRulesCommitmentDefinition, WritingRulesCommitmentDefinition, SampleCommitmentDefinition, SampleCommitmentDefinition, FormatCommitmentDefinition, FormatCommitmentDefinition, TemplateCommitmentDefinition, TemplateCommitmentDefinition, FromCommitmentDefinition, ImportCommitmentDefinition, ImportCommitmentDefinition, ModelCommitmentDefinition, ModelCommitmentDefinition, ActionCommitmentDefinition, ActionCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaImageCommitmentDefinition, MetaColorCommitmentDefinition, MetaFontCommitmentDefinition, MetaLinkCommitmentDefinition, MetaDomainCommitmentDefinition, MetaDescriptionCommitmentDefinition, MetaDisclaimerCommitmentDefinition, MetaFullnameCommitmentDefinition, MetaIdCommitmentDefinition, MetaInputPlaceholderCommitmentDefinition, MetaThinkingMessageCommitmentDefinition, MetaVisibilityCommitmentDefinition, MetaVoiceCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, GoalCommitmentDefinition, GoalCommitmentDefinition, InitialMessageCommitmentDefinition, UserMessageCommitmentDefinition, InternalMessageCommitmentDefinition, AgentMessageCommitmentDefinition, MessageSuffixCommitmentDefinition, MessageCommitmentDefinition, MessageCommitmentDefinition, ScenarioCommitmentDefinition, ScenarioCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DictionaryCommitmentDefinition, OpenCommitmentDefinition, ClosedCommitmentDefinition, TeamCommitmentDefinition, UseUserLocationCommitmentDefinition, UseCalendarCommitmentDefinition, UsePopupCommitmentDefinition, UseImageGeneratorCommitmentDefinition, UseMcpCommitmentDefinition, UsePrivacyCommitmentDefinition, UseProjectCommitmentDefinition, NotYetImplementedCommitmentDefinition<"EXPECT">, NotYetImplementedCommitmentDefinition<"BEHAVIOUR">, NotYetImplementedCommitmentDefinition<"BEHAVIOURS">, NotYetImplementedCommitmentDefinition<"AVOID">, NotYetImplementedCommitmentDefinition<"AVOIDANCE">, NotYetImplementedCommitmentDefinition<"CONTEXT">];

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.114.0-24`).
+ * It follows semantic versioning (e.g., `0.114.0-26`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/markdown-utils",
-    "version": "0.114.0-25",
+    "version": "0.114.0-27",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,

package/umd/index.umd.js

@@ -25,7 +25,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.114.0-25';
+    const PROMPTBOOK_ENGINE_VERSION = '0.114.0-27';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name

package/umd/src/cli/cli-commands/common/harness/$applyHarnessInstallationStatus.d.ts

@@ -2,7 +2,7 @@ import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
 /**
  * Reports one detected harness installation status and offers to install or update the harness.
  *
- * Note: `$` is used to indicate that this function is not a pure function - it asks the user and installs npm packages
+ * Note: `$` is used to indicate that this function is not a pure function - it asks the user and installs software
  *
  * @private internal utility of `promptbookCli`
  */

package/umd/src/cli/cli-commands/common/harness/$resolveHarnessCommandPath.d.ts

@@ -0,0 +1,14 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+/**
+ * Finds out which file is really executed when the harness command runs.
+ *
+ * The lookup deliberately uses the very same `PATH` which runs the harness, so it reports the copy of the
+ * harness which Promptbook itself would use. Symbolic links are followed, because installers like the
+ * standalone OpenAI Codex installer only link their package into a directory on `PATH`.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs a command in a shell
+ *
+ * @returns Resolved path of the harness command or `null` when the command is not available
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $resolveHarnessCommandPath(definition: HarnessDefinition): Promise<string | null>;

package/umd/src/cli/cli-commands/common/harness/$resolveHarnessInstallationOrigin.d.ts

@@ -0,0 +1,10 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationOrigin } from './HarnessInstallationOrigin';
+/**
+ * Finds out where one CLI coding harness is really installed and which tool manages it.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs shell commands
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $resolveHarnessInstallationOrigin(definition: HarnessDefinition): Promise<HarnessInstallationOrigin>;

package/umd/src/cli/cli-commands/common/harness/$runHarnessInstallationCommand.d.ts

@@ -0,0 +1,43 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+/**
+ * What one harness installation command does with the harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationOperation = 'install' | 'update';
+/**
+ * Options of one command which installs or updates a CLI coding harness.
+ *
+ * @private internal utility of `$runHarnessInstallationCommand`
+ */
+type HarnessInstallationCommandOptions = {
+    /**
+     * Harness which is installed or updated.
+     */
+    readonly definition: HarnessDefinition;
+    /**
+     * What the command does with the harness.
+     */
+    readonly operation: HarnessInstallationOperation;
+    /**
+     * Shell command which does it.
+     */
+    readonly command: string;
+    /**
+     * Extra environment variables required by the command.
+     */
+    readonly environment?: Readonly<Record<string, string>>;
+};
+/**
+ * Runs one command which installs or updates a CLI coding harness.
+ *
+ * A failed installation is reported but never aborts the running command, because the harness check
+ * is only an assistant - the command itself may still work with a manually managed harness.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it installs software
+ *
+ * @returns `true` when the command succeeded, `false` when it failed
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $runHarnessInstallationCommand(options: HarnessInstallationCommandOptions): Promise<boolean>;
+export {};

package/umd/src/cli/cli-commands/common/harness/HarnessDefinition.d.ts

@@ -1,4 +1,24 @@
 import type { PromptRunnerHarnessName } from '../promptRunnerCliOptions';
+/**
+ * Description of a standalone *(self-managed)* installation of one CLI coding harness.
+ *
+ * Some harnesses are also distributed by their own installer which puts the harness outside of npm and
+ * updates it in place. Such an installation must never be updated with `npm install -g`, because that
+ * installs a second copy of the harness instead of updating the one which is really used.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessStandaloneInstallation = {
+    /**
+     * Directory names which appear in the resolved path of a standalone installation of the harness,
+     * for example `.codex` in `~/.codex/packages/standalone/current/bin/codex`.
+     */
+    readonly directoryNames: ReadonlyArray<string>;
+    /**
+     * Command which updates the standalone installation in place.
+     */
+    readonly updateCommand: string;
+};
 /**
  * Static description of one supported CLI coding harness.
  *
@@ -25,6 +45,12 @@ export type HarnessDefinition = {
      * Extra environment variables required by the global npm installation of this harness.
      */
     readonly npmInstallEnvironment?: Readonly<Record<string, string>>;
+    /**
+     * How a standalone installation of this harness is recognized and updated.
+     *
+     * Harnesses which are distributed only through npm leave this undefined.
+     */
+    readonly standaloneInstallation?: HarnessStandaloneInstallation;
 };
 /**
  * Single source of truth about how each supported CLI coding harness is installed and detected.

package/umd/src/cli/cli-commands/common/harness/HarnessInstallationOrigin.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Way in which the globally available harness command got onto the current machine.
+ *
+ * - `npm-global` the command comes from a global npm installation, so `npm install -g` really updates it
+ * - `standalone` the command was installed by the own installer of the harness and updates itself in place
+ * - `homebrew` the command is managed by Homebrew, so only `brew` may update it
+ * - `unknown` the command lives somewhere else or could not be located at all
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationMethod = 'npm-global' | 'standalone' | 'homebrew' | 'unknown';
+/**
+ * Place where the harness command really lives together with the way it was installed there.
+ *
+ * Knowing the origin is what keeps an update from installing a **second** copy of a harness which is
+ * managed outside of npm, for example the standalone installation of OpenAI Codex.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessInstallationOrigin = {
+    /**
+     * Resolved path of the harness command with every symbolic link followed
+     * or `null` when the command could not be located.
+     */
+    readonly commandPath: string | null;
+    /**
+     * Way in which the harness command was installed.
+     */
+    readonly installationMethod: HarnessInstallationMethod;
+};
+/**
+ * Origin used when the harness command was not looked up at all, for example when the update check is disabled.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const UNKNOWN_HARNESS_INSTALLATION_ORIGIN: HarnessInstallationOrigin;

package/umd/src/cli/cli-commands/common/harness/HarnessInstallationStatus.d.ts

@@ -1,4 +1,5 @@
 import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationOrigin } from './HarnessInstallationOrigin';
 /**
  * Result of comparing the globally installed harness version with the newest published one.
  *
@@ -33,4 +34,8 @@ export type HarnessInstallationStatus = {
      * Newest version published to npm or `null` when it could not be resolved.
      */
     readonly latestVersion: string | null;
+    /**
+     * Place where the harness command lives together with the way it was installed there.
+     */
+    readonly installationOrigin: HarnessInstallationOrigin;
 };

package/umd/src/cli/cli-commands/common/harness/HarnessUpdatePlan.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How an outdated CLI coding harness can be brought up to date where it is really installed.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type HarnessUpdatePlan = {
+    /**
+     * Command which updates the harness in place
+     * or `null` when the installation is not understood well enough to name one.
+     */
+    readonly command: string | null;
+    /**
+     * Whether Promptbook may run the command itself instead of only printing it.
+     *
+     * Only installations which Promptbook can update without any side effect are updated automatically,
+     * everything else is left to the user together with the instructions.
+     */
+    readonly isRunnableByPromptbook: boolean;
+    /**
+     * Extra environment variables required by the update command.
+     */
+    readonly environment?: Readonly<Record<string, string>>;
+};

package/umd/src/cli/cli-commands/common/harness/buildHarnessInstallCommand.d.ts

@@ -2,9 +2,12 @@ import type { HarnessDefinition } from './HarnessDefinition';
 /**
  * Builds the shell command which installs or updates one CLI coding harness globally.
  *
- * The very same command is executed by `$installHarness` and printed as the manual fallback,
+ * The very same command is executed by `$runHarnessInstallationCommand` and printed as the manual fallback,
  * so the user always sees exactly what Promptbook would run.
  *
+ * Note: This command installs the harness through npm, so it may only update a harness which npm really owns,
+ * see `resolveHarnessUpdatePlan`.
+ *
  * @private internal utility of `promptbookCli`
  */
 export declare function buildHarnessInstallCommand(definition: HarnessDefinition): string;

package/umd/src/cli/cli-commands/common/harness/formatHarnessManualUpdateInstruction.d.ts

@@ -0,0 +1,8 @@
+import type { HarnessInstallationStatus } from './HarnessInstallationStatus';
+import type { HarnessUpdatePlan } from './HarnessUpdatePlan';
+/**
+ * Formats the instruction shown when an outdated harness must be updated by the user.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function formatHarnessManualUpdateInstruction(status: HarnessInstallationStatus, updatePlan: HarnessUpdatePlan): string;

package/umd/src/cli/cli-commands/common/harness/formatHarnessManualUpdateInstruction.test.d.ts

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

package/umd/src/cli/cli-commands/common/harness/resolveHarnessInstallationMethodFromPaths.d.ts

@@ -0,0 +1,31 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationMethod } from './HarnessInstallationOrigin';
+/**
+ * Options describing where the harness command was found.
+ *
+ * @private internal utility of `resolveHarnessInstallationMethodFromPaths`
+ */
+type HarnessInstallationPaths = {
+    /**
+     * Harness whose command was located.
+     */
+    readonly definition: HarnessDefinition;
+    /**
+     * Resolved path of the harness command with every symbolic link followed.
+     */
+    readonly commandPath: string;
+    /**
+     * Root directory of global npm installations or `null` when npm could not be asked for it.
+     */
+    readonly npmGlobalPrefixPath: string | null;
+};
+/**
+ * Decides how a harness command was installed from the place where it really lives.
+ *
+ * Only a command which npm owns may be updated with `npm install -g`, every other command has to be
+ * updated where it is installed, otherwise the update silently adds a second copy of the harness.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function resolveHarnessInstallationMethodFromPaths(paths: HarnessInstallationPaths): HarnessInstallationMethod;
+export {};

package/umd/src/cli/cli-commands/common/harness/resolveHarnessInstallationMethodFromPaths.test.d.ts

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

package/umd/src/cli/cli-commands/common/harness/resolveHarnessUpdatePlan.d.ts

@@ -0,0 +1,12 @@
+import type { HarnessDefinition } from './HarnessDefinition';
+import type { HarnessInstallationMethod } from './HarnessInstallationOrigin';
+import type { HarnessUpdatePlan } from './HarnessUpdatePlan';
+/**
+ * Decides how one outdated CLI coding harness should be updated.
+ *
+ * The plan follows the way the harness was installed, because `npm install -g` updates only a harness
+ * which npm owns and installs a **second** copy of every other one.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function resolveHarnessUpdatePlan(definition: HarnessDefinition, installationMethod: HarnessInstallationMethod): HarnessUpdatePlan;

package/umd/src/cli/cli-commands/common/harness/resolveHarnessUpdatePlan.test.d.ts

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

package/umd/src/cli/cli-commands/common/npm/$resolveNpmGlobalPrefixPath.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reads the root directory under which npm installs global packages.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it runs npm
+ *
+ * @returns The global npm prefix or `null` when npm could not be asked for it
+ * @private internal utility of `promptbookCli`
+ */
+export declare function $resolveNpmGlobalPrefixPath(): Promise<string | null>;

package/umd/src/commitments/WRITING_RULES/WRITING_RULES.d.ts

@@ -3,23 +3,30 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
 /**
  * `WRITING RULES` commitment definition.
  *
- * It adds constraints that apply strictly to writing style and presentation
- * rather than task-solving behavior.
+ * The `WRITING RULES`/`WRITING RULE` commitment adds constraints that apply strictly to writing style
+ * and presentation rather than task-solving behavior.
+ *
+ * Example usage in agent source:
+ *
+ * ```book
+ * WRITING RULES Keep every response under 120 words
+ * WRITING RULE Always end the message with an emoji
+ * ```
  *
  * @private [🪔] Maybe export the commitments through some package
  */
-export declare class WritingRulesCommitmentDefinition extends BaseCommitmentDefinition<'WRITING RULES'> {
-    constructor();
+export declare class WritingRulesCommitmentDefinition extends BaseCommitmentDefinition<'WRITING RULES' | 'WRITING RULE'> {
+    constructor(type?: 'WRITING RULES' | 'WRITING RULE');
     /**
-     * Short one-line description of `WRITING RULES`.
+     * Short one-line description of `WRITING RULES`/`WRITING RULE`.
      */
     get description(): string;
     /**
-     * Icon for `WRITING RULES`.
+     * Icon for `WRITING RULES`/`WRITING RULE`.
      */
     get icon(): string;
     /**
-     * Markdown documentation for `WRITING RULES`.
+     * Markdown documentation for `WRITING RULES`/`WRITING RULE` commitment.
      */
     get documentation(): string;
     applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements;

package/umd/src/commitments/index.d.ts

@@ -55,4 +55,4 @@ import { NotYetImplementedCommitmentDefinition } from './_base/NotYetImplemented
  *
  * @private Use functions to access commitments instead of this array directly
  */
-export declare const COMMITMENT_REGISTRY: readonly [PersonaCommitmentDefinition, PersonaCommitmentDefinition, KnowledgeCommitmentDefinition, StyleCommitmentDefinition, StyleCommitmentDefinition, RuleCommitmentDefinition, RuleCommitmentDefinition, LanguageCommitmentDefinition, LanguageCommitmentDefinition, WritingSampleCommitmentDefinition, WritingRulesCommitmentDefinition, SampleCommitmentDefinition, SampleCommitmentDefinition, FormatCommitmentDefinition, FormatCommitmentDefinition, TemplateCommitmentDefinition, TemplateCommitmentDefinition, FromCommitmentDefinition, ImportCommitmentDefinition, ImportCommitmentDefinition, ModelCommitmentDefinition, ModelCommitmentDefinition, ActionCommitmentDefinition, ActionCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaImageCommitmentDefinition, MetaColorCommitmentDefinition, MetaFontCommitmentDefinition, MetaLinkCommitmentDefinition, MetaDomainCommitmentDefinition, MetaDescriptionCommitmentDefinition, MetaDisclaimerCommitmentDefinition, MetaFullnameCommitmentDefinition, MetaIdCommitmentDefinition, MetaInputPlaceholderCommitmentDefinition, MetaThinkingMessageCommitmentDefinition, MetaVisibilityCommitmentDefinition, MetaVoiceCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, GoalCommitmentDefinition, GoalCommitmentDefinition, InitialMessageCommitmentDefinition, UserMessageCommitmentDefinition, InternalMessageCommitmentDefinition, AgentMessageCommitmentDefinition, MessageSuffixCommitmentDefinition, MessageCommitmentDefinition, MessageCommitmentDefinition, ScenarioCommitmentDefinition, ScenarioCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DictionaryCommitmentDefinition, OpenCommitmentDefinition, ClosedCommitmentDefinition, TeamCommitmentDefinition, UseUserLocationCommitmentDefinition, UseCalendarCommitmentDefinition, UsePopupCommitmentDefinition, UseImageGeneratorCommitmentDefinition, UseMcpCommitmentDefinition, UsePrivacyCommitmentDefinition, UseProjectCommitmentDefinition, NotYetImplementedCommitmentDefinition<"EXPECT">, NotYetImplementedCommitmentDefinition<"BEHAVIOUR">, NotYetImplementedCommitmentDefinition<"BEHAVIOURS">, NotYetImplementedCommitmentDefinition<"AVOID">, NotYetImplementedCommitmentDefinition<"AVOIDANCE">, NotYetImplementedCommitmentDefinition<"CONTEXT">];
+export declare const COMMITMENT_REGISTRY: readonly [PersonaCommitmentDefinition, PersonaCommitmentDefinition, KnowledgeCommitmentDefinition, StyleCommitmentDefinition, StyleCommitmentDefinition, RuleCommitmentDefinition, RuleCommitmentDefinition, LanguageCommitmentDefinition, LanguageCommitmentDefinition, WritingSampleCommitmentDefinition, WritingRulesCommitmentDefinition, WritingRulesCommitmentDefinition, SampleCommitmentDefinition, SampleCommitmentDefinition, FormatCommitmentDefinition, FormatCommitmentDefinition, TemplateCommitmentDefinition, TemplateCommitmentDefinition, FromCommitmentDefinition, ImportCommitmentDefinition, ImportCommitmentDefinition, ModelCommitmentDefinition, ModelCommitmentDefinition, ActionCommitmentDefinition, ActionCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaImageCommitmentDefinition, MetaColorCommitmentDefinition, MetaFontCommitmentDefinition, MetaLinkCommitmentDefinition, MetaDomainCommitmentDefinition, MetaDescriptionCommitmentDefinition, MetaDisclaimerCommitmentDefinition, MetaFullnameCommitmentDefinition, MetaIdCommitmentDefinition, MetaInputPlaceholderCommitmentDefinition, MetaThinkingMessageCommitmentDefinition, MetaVisibilityCommitmentDefinition, MetaVoiceCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, GoalCommitmentDefinition, GoalCommitmentDefinition, InitialMessageCommitmentDefinition, UserMessageCommitmentDefinition, InternalMessageCommitmentDefinition, AgentMessageCommitmentDefinition, MessageSuffixCommitmentDefinition, MessageCommitmentDefinition, MessageCommitmentDefinition, ScenarioCommitmentDefinition, ScenarioCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DictionaryCommitmentDefinition, OpenCommitmentDefinition, ClosedCommitmentDefinition, TeamCommitmentDefinition, UseUserLocationCommitmentDefinition, UseCalendarCommitmentDefinition, UsePopupCommitmentDefinition, UseImageGeneratorCommitmentDefinition, UseMcpCommitmentDefinition, UsePrivacyCommitmentDefinition, UseProjectCommitmentDefinition, NotYetImplementedCommitmentDefinition<"EXPECT">, NotYetImplementedCommitmentDefinition<"BEHAVIOUR">, NotYetImplementedCommitmentDefinition<"BEHAVIOURS">, NotYetImplementedCommitmentDefinition<"AVOID">, NotYetImplementedCommitmentDefinition<"AVOIDANCE">, NotYetImplementedCommitmentDefinition<"CONTEXT">];

package/umd/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.114.0-24`).
+ * It follows semantic versioning (e.g., `0.114.0-26`).
  *
  * @generated
  */

package/esm/src/cli/cli-commands/common/harness/$installHarness.d.ts

@@ -1,13 +0,0 @@
-import type { HarnessDefinition } from './HarnessDefinition';
-/**
- * Installs or updates one CLI coding harness globally through npm.
- *
- * A failed installation is reported but never aborts the running command, because the harness check
- * is only an assistant - the command itself may still work with a manually managed harness.
- *
- * Note: `$` is used to indicate that this function is not a pure function - it installs a global npm package
- *
- * @returns `true` when the harness has been installed, `false` when the installation failed
- * @private internal utility of `promptbookCli`
- */
-export declare function $installHarness(definition: HarnessDefinition): Promise<boolean>;

package/umd/src/cli/cli-commands/common/harness/$installHarness.d.ts

@@ -1,13 +0,0 @@
-import type { HarnessDefinition } from './HarnessDefinition';
-/**
- * Installs or updates one CLI coding harness globally through npm.
- *
- * A failed installation is reported but never aborts the running command, because the harness check
- * is only an assistant - the command itself may still work with a manually managed harness.
- *
- * Note: `$` is used to indicate that this function is not a pure function - it installs a global npm package
- *
- * @returns `true` when the harness has been installed, `false` when the installation failed
- * @private internal utility of `promptbookCli`
- */
-export declare function $installHarness(definition: HarnessDefinition): Promise<boolean>;