@promptbook/cli 0.112.0-99 → 0.113.0-0

package/src/cli/cli-commands/coder/waitOptions.ts

@@ -0,0 +1,24 @@
+import { parseDuration } from '../../../../scripts/run-codex-prompts/common/parseDuration';
+
+/**
+ * Default wait duration applied before retrying a prompt round after an error (10 minutes).
+ *
+ * @private internal constant of `ptbk coder` wait handling
+ */
+export const DEFAULT_WAIT_AFTER_ERROR_MS = 10 * 60 * 1000;
+
+/**
+ * Parses an optional Commander duration string and returns the resolved milliseconds.
+ *
+ * Returns `defaultMs` when the flag was not provided or was provided without a non-empty value.
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export function parseOptionalWaitDuration(value: string | undefined, defaultMs: number): number {
+    if (typeof value !== 'string' || value === '') {
+        return defaultMs;
+    }
+    return parseDuration(value);
+}
+
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/cli/cli-commands/coder.ts

@@ -6,9 +6,11 @@ import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../utils/organization/$side_effect';
 import { $initializeCoderFindFreshEmojiTagCommand } from './coder/find-fresh-emoji-tags';
 import { $initializeCoderFindRefactorCandidatesCommand } from './coder/find-refactor-candidates';
+import { $initializeCoderFindUnwrittenCommand } from './coder/find-unwritten';
 import { $initializeCoderGenerateBoilerplatesCommand } from './coder/generate-boilerplates';
 import { $initializeCoderInitCommand } from './coder/init';
 import { $initializeCoderRunCommand } from './coder/run';
+import { $initializeCoderServerCommand } from './coder/server';
 import { $initializeCoderVerifyCommand } from './coder/verify';
 
 /**
@@ -36,7 +38,9 @@ export function $initializeCoderCommand(program: Program): $side_effect {
             - init: Initialize coder configuration in current project
             - generate-boilerplates: Generate prompt boilerplate files
             - find-refactor-candidates: Find files that need refactoring
+            - find-unwritten: List prompt sections that still need to be authored
             - run: Run coding prompts with AI agents
+            - server: Start a long-running coder server with a kanban web UI
             - verify: Verify completed prompts
             - find-fresh-emoji-tags: Find unused emoji tags
         `),
@@ -46,7 +50,9 @@ export function $initializeCoderCommand(program: Program): $side_effect {
     $initializeCoderInitCommand(coderCommand);
     $initializeCoderGenerateBoilerplatesCommand(coderCommand);
     $initializeCoderFindRefactorCandidatesCommand(coderCommand);
+    $initializeCoderFindUnwrittenCommand(coderCommand);
     $initializeCoderRunCommand(coderCommand);
+    $initializeCoderServerCommand(coderCommand);
     $initializeCoderVerifyCommand(coderCommand);
     $initializeCoderFindFreshEmojiTagCommand(coderCommand);
 

package/src/cli/cli-commands/common/promptRunnerCliOptions.ts

@@ -6,48 +6,28 @@ import {
 import { spaceTrim } from 'spacetrim';
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
 import { THINKING_LEVEL_VALUES } from '../coder/ThinkingLevel';
+import {
+    CLI_AGENT_HARNESS_NAMES,
+    PTBK_HARNESS_ENV,
+    PTBK_MODEL_ENV,
+    PTBK_THINKING_LEVEL_ENV,
+} from '../../../book-3.0/cliAgentEnv';
 
-/**
- * Runner identifiers supported by Promptbook CLI agent orchestration commands.
- *
- * @private internal utility of `promptbookCli`
- */
-export const PROMPT_RUNNER_AGENT_NAMES = [
-    'openai-codex',
-    'github-copilot',
-    'cline',
-    'claude-code',
-    'opencode',
-    'gemini',
-] as const;
-
-/**
- * Environment variable used as the default runner identifier when `--agent` is omitted.
- *
- * @private internal utility of `promptbookCli`
- */
-export const PTBK_AGENT_ENV = 'PTBK_AGENT';
-
-/**
- * Environment variable used as the default runner model when `--model` is omitted.
- *
- * @private internal utility of `promptbookCli`
- */
-export const PTBK_MODEL_ENV = 'PTBK_MODEL';
+export { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV };
 
 /**
- * Environment variable used as the default runner thinking level when `--thinking-level` is omitted.
+ * Runner identifiers supported by Promptbook CLI agent orchestration commands.
  *
  * @private internal utility of `promptbookCli`
  */
-export const PTBK_THINKING_LEVEL_ENV = 'PTBK_THINKING_LEVEL';
+export const PROMPT_RUNNER_HARNESS_NAMES = CLI_AGENT_HARNESS_NAMES;
 
 /**
  * Runner identifier supported by Promptbook CLI agent orchestration commands.
  *
  * @private internal utility of `promptbookCli`
  */
-export type PromptRunnerAgentName = (typeof PROMPT_RUNNER_AGENT_NAMES)[number];
+export type PromptRunnerHarnessName = (typeof PROMPT_RUNNER_HARNESS_NAMES)[number];
 
 /**
  * Commander option bag for shared runner flags.
@@ -55,7 +35,7 @@ export type PromptRunnerAgentName = (typeof PROMPT_RUNNER_AGENT_NAMES)[number];
  * @private internal utility of `promptbookCli`
  */
 export type PromptRunnerCliOptions = {
-    readonly agent?: string;
+    readonly harness?: string;
     readonly model?: string;
     readonly ui: boolean;
     readonly thinkingLevel?: ThinkingLevel;
@@ -74,7 +54,7 @@ export type PromptRunnerCliOptions = {
  */
 export type PromptRunnerSelectionCliOptions = Pick<
     PromptRunnerCliOptions,
-    'agent' | 'model' | 'ui' | 'thinkingLevel' | 'allowCredits'
+    'harness' | 'model' | 'ui' | 'thinkingLevel' | 'allowCredits'
 >;
 
 /**
@@ -83,7 +63,7 @@ export type PromptRunnerSelectionCliOptions = Pick<
  * @private internal utility of `promptbookCli`
  */
 export type NormalizedPromptRunnerCliOptions = {
-    readonly agentName?: PromptRunnerAgentName;
+    readonly agentName?: PromptRunnerHarnessName;
     readonly model?: string;
     readonly noUi: boolean;
     readonly thinkingLevel?: ThinkingLevel;
@@ -121,11 +101,11 @@ export const PROMPT_RUNNER_DESCRIPTION = spaceTrim(`
 `);
 
 /**
- * Commander description for the `--agent` option.
+ * Commander description for the `--harness` option.
  *
  * @private internal utility of `promptbookCli`
  */
-export const PROMPT_RUNNER_AGENT_OPTION_DESCRIPTION =
+export const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION =
     'Select runner: openai-codex, github-copilot, cline, claude-code, opencode, gemini (required for non-dry-run)';
 
 /**
@@ -146,7 +126,9 @@ export const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION = spaceTrim(`
  * @private internal utility of `promptbookCli`
  */
 export function addPromptRunnerSelectionOptions(command: Program): void {
-    command.addOption(new Option('--agent <agent-name>', PROMPT_RUNNER_AGENT_OPTION_DESCRIPTION).env(PTBK_AGENT_ENV));
+    command.addOption(
+        new Option('--harness <harness-name>', PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION).env(PTBK_HARNESS_ENV),
+    );
     command.addOption(new Option('--model <model>', PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION).env(PTBK_MODEL_ENV));
 }
 
@@ -227,7 +209,7 @@ export function normalizePromptRunnerSelectionCliOptions(
     },
 ): NormalizedPromptRunnerSelectionCliOptions {
     return {
-        agentName: resolvePromptRunnerAgentName(cliOptions.agent, options),
+        agentName: resolvePromptRunnerHarnessName(cliOptions.harness, options),
         model: cliOptions.model,
         noUi: !cliOptions.ui,
         thinkingLevel: cliOptions.thinkingLevel,
@@ -236,38 +218,40 @@ export function normalizePromptRunnerSelectionCliOptions(
 }
 
 /**
- * Parses and validates one runner agent name.
+ * Parses and validates one runner harness name.
  */
-function resolvePromptRunnerAgentName(
-    agent: string | undefined,
+function resolvePromptRunnerHarnessName(
+    harness: string | undefined,
     options: {
         readonly isAgentRequired: boolean;
     },
-): PromptRunnerAgentName | undefined {
-    if (!agent) {
+): PromptRunnerHarnessName | undefined {
+    if (!harness) {
         if (!options.isAgentRequired) {
             return undefined;
         }
 
         throw new Error(
             colors.red(
-                'You must choose an agent using --agent <openai-codex|github-copilot|cline|claude-code|opencode|gemini>',
+                'You must choose a harness using --harness <openai-codex|github-copilot|cline|claude-code|opencode|gemini>',
             ),
         );
     }
 
-    if (isPromptRunnerAgentName(agent)) {
-        return agent;
+    if (isPromptRunnerHarnessName(harness)) {
+        return harness;
     }
 
-    throw new Error(colors.red(`Invalid agent "${agent}". Must be one of: ${PROMPT_RUNNER_AGENT_NAMES.join(', ')}`));
+    throw new Error(
+        colors.red(`Invalid harness "${harness}". Must be one of: ${PROMPT_RUNNER_HARNESS_NAMES.join(', ')}`),
+    );
 }
 
 /**
- * Checks whether a string is one supported runner agent name.
+ * Checks whether a string is one supported runner harness name.
  */
-function isPromptRunnerAgentName(agent: string): agent is PromptRunnerAgentName {
-    return PROMPT_RUNNER_AGENT_NAMES.includes(agent as PromptRunnerAgentName);
+function isPromptRunnerHarnessName(harness: string): harness is PromptRunnerHarnessName {
+    return PROMPT_RUNNER_HARNESS_NAMES.includes(harness as PromptRunnerHarnessName);
 }
 
 // Note: [🟡] Code for CLI runner options [promptRunnerCliOptions](src/cli/cli-commands/common/promptRunnerCliOptions.ts) should never be published outside of `@promptbook/cli`

package/src/cli/common/$deprecateCliCommand.ts

@@ -1,5 +1,6 @@
 import colors from 'colors';
 import { Command } from 'commander';
+import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../utils/organization/$side_effect';
 
 /**
@@ -8,7 +9,15 @@ import type { $side_effect } from '../../utils/organization/$side_effect';
  * @private utility of CLI
  */
 export function $deprecateCliCommand(command: Command, deprecationMessage: string): $side_effect {
-    command.description(`${command.description()}\n\nDeprecated: ${deprecationMessage}`);
+    command.description(
+        spaceTrim(
+            (block) => `
+                ${block(command.description())}
+
+                Deprecated: ${block(deprecationMessage)}
+            `,
+        ),
+    );
     command.hook('preAction', () => {
         console.warn(colors.yellow(createDeprecatedCliCommandWarning(command, deprecationMessage)));
     });

package/src/cli/promptbookCli.ts

@@ -6,6 +6,7 @@ import { EnvironmentMismatchError } from '../errors/EnvironmentMismatchError';
 import { $isRunningInNode } from '../utils/environment/$isRunningInNode';
 import { PROMPTBOOK_ENGINE_VERSION } from '../version';
 import { $initializeAboutCommand } from './cli-commands/about';
+import { $initializeAgentCommand } from './cli-commands/agent';
 import { $initializeAgentFolderCommand } from './cli-commands/agent-folder';
 import { $initializeAgentsServerCommand } from './cli-commands/agents-server';
 import { $initializeCoderCommand } from './cli-commands/coder';
@@ -93,6 +94,7 @@ export async function promptbookCli(): Promise<void> {
     $initializeListScrapersCommand(program);
     $initializeStartAgentsServerCommand(program);
     $initializeStartPipelinesServerCommand(program);
+    $initializeAgentCommand(program);
     $initializeAgentFolderCommand(program);
     $initializeAgentsServerCommand(program);
     $initializeCoderCommand(program);

package/src/collection/agent-collection/CreateAgentInput.ts

@@ -1,4 +1,9 @@
 import type { string_book } from '../../book-2.0/agent-source/string_book';
+import {
+    AGENT_VISIBILITY_VALUES,
+    normalizeAgentVisibility,
+    type AgentVisibility,
+} from '../../book-2.0/agent-source/agentSourceVisibility';
 import { LimitReachedError } from '../../errors/LimitReachedError';
 import { ParseError } from '../../errors/ParseError';
 import type { LlmToolDefinition } from '../../types/LlmToolDefinition';
@@ -9,14 +14,14 @@ import { spaceTrim } from '../../utils/organization/spaceTrim';
  *
  * @private shared create-agent contract
  */
-export const CREATE_AGENT_VISIBILITY_VALUES = ['PRIVATE', 'UNLISTED', 'PUBLIC'] as const;
+export const CREATE_AGENT_VISIBILITY_VALUES = AGENT_VISIBILITY_VALUES;
 
 /**
  * Supported visibility options for agent creation.
  *
  * @private shared create-agent contract
  */
-export type CreateAgentVisibility = (typeof CREATE_AGENT_VISIBILITY_VALUES)[number];
+export type CreateAgentVisibility = AgentVisibility;
 
 /**
  * Canonical input payload for creating one persisted agent entity.
@@ -244,8 +249,8 @@ function parseOptionalVisibility(rawValue: unknown): CreateAgentVisibility | und
         );
     }
 
-    const isSupportedVisibility = CREATE_AGENT_VISIBILITY_VALUES.includes(rawValue as CreateAgentVisibility);
-    if (!isSupportedVisibility) {
+    const visibility = normalizeAgentVisibility(rawValue);
+    if (!visibility) {
         throw new ParseError(
             spaceTrim(`
                 Invalid create-agent payload.
@@ -255,5 +260,5 @@ function parseOptionalVisibility(rawValue: unknown): CreateAgentVisibility | und
         );
     }
 
-    return rawValue as CreateAgentVisibility;
+    return visibility;
 }

package/src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase.ts

@@ -49,6 +49,19 @@ function normalizeHistoryVersionName(versionName: string | null | undefined): st
     return normalizedVersionName.length > 0 ? normalizedVersionName : null;
 }
 
+/**
+ * Builds a Supabase `.or()` filter for agent name or permanent id lookups.
+ *
+ * @param agentNameOrPermanentId - Agent name or stable permanent identifier to match.
+ * @returns `.or()` filter string safe to pass to Supabase.
+ *
+ * @private internal helper of `AgentCollectionInSupabase`
+ */
+function buildAgentNameOrPermanentIdFilter(agentNameOrPermanentId: string): string {
+    const encodedAgentIdentifier = encodeURIComponent(agentNameOrPermanentId);
+    return `agentName.eq.${encodedAgentIdentifier},permanentId.eq.${encodedAgentIdentifier}`;
+}
+
 /**
  * One saved Agent history row without the full source payload.
  */
@@ -69,6 +82,16 @@ type AgentHistorySnapshot = AgentHistoryMetadata & {
     readonly agentSource: string;
 };
 
+/**
+ * Minimal database row used to build public agent information.
+ *
+ * @private internal type of `AgentCollectionInSupabase`
+ */
+type AgentBasicInformationRow = Pick<
+    AgentsDatabaseSchema['public']['Tables']['Agent']['Row'],
+    'agentName' | 'agentProfile' | 'permanentId'
+>;
+
 /**
  * Agent collection stored in a Supabase table.
  *
@@ -127,24 +150,78 @@ export class AgentCollectionInSupabase /* TODO: [🌈][🐱‍🚀] implements A
             console.info(`Found ${selectResult.data.length} agents in directory`);
         }
 
-        return selectResult.data.map(({ agentName, agentProfile, permanentId }) => {
-            if (isVerbose && (agentProfile as AgentBasicInformation).agentName !== agentName) {
-                console.warn(
-                    spaceTrim(`
+        return selectResult.data.map((row) => this.mapAgentBasicInformationRow(row, isVerbose));
+    }
+
+    /**
+     * Finds one active agent profile by its human-readable name or permanent id.
+     *
+     * This keeps route-level lookups from loading the whole agent collection when only
+     * one canonical route identifier is needed.
+     *
+     * @param agentNameOrPermanentId - Agent name or stable permanent identifier.
+     * @returns Matching active agent profile or `null` when not found.
+     *
+     * @public exported from `@promptbook/core`
+     */
+    public async findAgentBasicInformation(
+        agentNameOrPermanentId: string_agent_name | string_agent_permanent_id,
+    ): Promise<AgentBasicInformation | null> {
+        const { isVerbose = DEFAULT_IS_VERBOSE } = this.options || {};
+        const selectResult = await this.supabaseClient
+            .from(this.getTableName('Agent'))
+            .select('agentName,agentProfile,permanentId')
+            .or(buildAgentNameOrPermanentIdFilter(agentNameOrPermanentId))
+            .is('deletedAt', null)
+            .order('createdAt', { ascending: true })
+            .limit(1);
+
+        if (selectResult.error) {
+            throw new DatabaseError(
+                spaceTrim(
+                    (block) => `
+
+                        Error fetching agent "${agentNameOrPermanentId}" from Supabase:
+
+                        ${block(selectResult.error.message)}
+                    `,
+                ),
+            );
+        }
+
+        const row = selectResult.data?.[0];
+        return row ? this.mapAgentBasicInformationRow(row, isVerbose) : null;
+    }
+
+    /**
+     * Converts one database row into public agent information.
+     *
+     * @param row - Database row carrying the persisted profile snapshot.
+     * @param isVerbose - Whether profile-name mismatches should be logged.
+     * @returns Agent profile with canonical database name and permanent id.
+     *
+     * @private internal helper of `AgentCollectionInSupabase`
+     */
+    private mapAgentBasicInformationRow(
+        { agentName, agentProfile, permanentId }: AgentBasicInformationRow,
+        isVerbose: boolean,
+    ): AgentBasicInformation {
+        if (isVerbose && (agentProfile as AgentBasicInformation).agentName !== agentName) {
+            console.warn(
+                spaceTrim(`
                         Agent name mismatch for agent "${agentName}". Using name from database.
 
                         agentName: "${agentName}"
                         agentProfile.agentName: "${(agentProfile as AgentBasicInformation).agentName}"
                     `),
-                );
-            }
+            );
+        }
 
-            return {
-                ...(agentProfile as AgentBasicInformation),
-                agentName,
-                permanentId: permanentId || (agentProfile as AgentBasicInformation).permanentId,
-            };
-        });
+        return {
+            ...(agentProfile as AgentBasicInformation),
+            agentName,
+            permanentId: permanentId || (agentProfile as AgentBasicInformation).permanentId,
+        };
     }
 
     /**
@@ -156,7 +233,7 @@ export class AgentCollectionInSupabase /* TODO: [🌈][🐱‍🚀] implements A
         const selectResult = await this.supabaseClient
             .from(this.getTableName('Agent'))
             .select('permanentId')
-            .or(`agentName.eq.${agentNameOrPermanentId},permanentId.eq.${agentNameOrPermanentId}`)
+            .or(buildAgentNameOrPermanentIdFilter(agentNameOrPermanentId))
             .order('createdAt', { ascending: true }) // Pick oldest if multiple match by name
             .limit(1);
 
@@ -175,7 +252,7 @@ export class AgentCollectionInSupabase /* TODO: [🌈][🐱‍🚀] implements A
         const selectResult = await this.supabaseClient
             .from(this.getTableName('Agent'))
             .select('agentSource')
-            .or(`agentName.eq.${agentNameOrPermanentId},permanentId.eq.${agentNameOrPermanentId}`)
+            .or(buildAgentNameOrPermanentIdFilter(agentNameOrPermanentId))
             .is('deletedAt', null)
             .order('createdAt', { ascending: true }) // Pick oldest if multiple match by name
             .limit(1);
@@ -245,7 +322,7 @@ export class AgentCollectionInSupabase /* TODO: [🌈][🐱‍🚀] implements A
     ): Promise<void> {
         const selectPreviousAgentResult = await this.supabaseClient
             .from(this.getTableName('Agent'))
-            .select('agentHash,agentName,permanentId')
+            .select('agentHash,agentName,permanentId,visibility')
             .eq('permanentId', permanentId)
             .single();
 
@@ -266,9 +343,12 @@ export class AgentCollectionInSupabase /* TODO: [🌈][🐱‍🚀] implements A
         const previousAgentName = selectPreviousAgentResult.data.agentName;
         const previousAgentHash = selectPreviousAgentResult.data.agentHash;
         const previousPermanentId = selectPreviousAgentResult.data.permanentId;
+        const previousVisibility = selectPreviousAgentResult.data.visibility;
 
-        const preparedAgentSource = prepareAgentSourceForPersistence(agentSource);
-        const { agentProfile, agentSource: normalizedAgentSource } = preparedAgentSource;
+        const preparedAgentSource = prepareAgentSourceForPersistence(agentSource, {
+            visibility: previousVisibility,
+        });
+        const { agentProfile, agentSource: normalizedAgentSource, visibility } = preparedAgentSource;
         let { permanentId: newPermanentId } = preparedAgentSource;
 
         const { agentHash, agentName } = agentProfile;
@@ -303,6 +383,7 @@ export class AgentCollectionInSupabase /* TODO: [🌈][🐱‍🚀] implements A
                 updatedAt: new Date().toISOString(),
                 agentHash: agentProfile.agentHash,
                 agentSource: normalizedAgentSource,
+                visibility: visibility ?? previousVisibility,
                 promptbookEngineVersion: PROMPTBOOK_ENGINE_VERSION,
             })
             .eq('permanentId', permanentId);

package/src/collection/agent-collection/constructors/agent-collection-in-supabase/createAgentPersistenceRecords.ts

@@ -51,8 +51,11 @@ export function createAgentPersistenceRecords(
     options: CreateAgentPersistenceRecordsOptions = {},
     createdAt: string = new Date().toISOString(),
 ): CreateAgentPersistenceRecordsResult {
-    const preparedAgentSource = prepareAgentSourceForPersistence(agentSource);
-    const { agentProfile, agentSource: normalizedAgentSource } = preparedAgentSource;
+    const preparedAgentSource = prepareAgentSourceForPersistence(agentSource, {
+        visibility: options.visibility,
+        isVisibilityOverride: options.visibility !== undefined,
+    });
+    const { agentProfile, agentSource: normalizedAgentSource, visibility } = preparedAgentSource;
     const permanentId = preparedAgentSource.permanentId || $randomBase58(14);
     const { agentName, agentHash } = agentProfile;
 
@@ -74,8 +77,8 @@ export function createAgentPersistenceRecords(
     if (options.sortOrder !== undefined) {
         agentInsertRecord.sortOrder = options.sortOrder;
     }
-    if (options.visibility !== undefined) {
-        agentInsertRecord.visibility = options.visibility;
+    if (visibility !== undefined) {
+        agentInsertRecord.visibility = visibility;
     }
 
     return {

package/src/collection/agent-collection/constructors/agent-collection-in-supabase/prepareAgentSourceForPersistence.ts

@@ -1,8 +1,30 @@
 import type { AgentBasicInformation } from '../../../../book-2.0/agent-source/AgentBasicInformation';
+import {
+    DEFAULT_AGENT_VISIBILITY,
+    parseAgentSourceVisibility,
+    setAgentSourceVisibility,
+    type AgentVisibility,
+} from '../../../../book-2.0/agent-source/agentSourceVisibility';
 import { parseAgentSource } from '../../../../book-2.0/agent-source/parseAgentSource';
 import type { string_book } from '../../../../book-2.0/agent-source/string_book';
 import type { string_agent_permanent_id } from '../../../../types/string_agent_name';
 
+/**
+ * Options used while preparing a source for persistence.
+ *
+ * @private shared persistence helper for `AgentCollectionInSupabase`
+ */
+export type PrepareAgentSourceForPersistenceOptions = {
+    /**
+     * Visibility value that should be written into the book when present.
+     */
+    readonly visibility?: AgentVisibility | null;
+    /**
+     * Whether `visibility` should replace an existing `META VISIBILITY` commitment.
+     */
+    readonly isVisibilityOverride?: boolean;
+};
+
 /**
  * Prepared agent source payload ready for database persistence.
  *
@@ -24,6 +46,10 @@ export type PreparedAgentSourceForPersistence = {
      * Permanent id extracted from the original source before stripping `META ID`.
      */
     readonly permanentId: string_agent_permanent_id | undefined;
+    /**
+     * Visibility parsed from the normalized source.
+     */
+    readonly visibility: AgentVisibility | undefined;
 };
 
 /**
@@ -36,20 +62,30 @@ export type PreparedAgentSourceForPersistence = {
  *
  * @private shared persistence helper for `AgentCollectionInSupabase`
  */
-export function prepareAgentSourceForPersistence(agentSource: string_book): PreparedAgentSourceForPersistence {
-    let agentProfile = parseAgentSource(agentSource);
-    const permanentId = agentProfile.permanentId;
+export function prepareAgentSourceForPersistence(
+    agentSource: string_book,
+    options: PrepareAgentSourceForPersistenceOptions = {},
+): PreparedAgentSourceForPersistence {
+    const originalAgentProfile = parseAgentSource(agentSource);
+    const permanentId = originalAgentProfile.permanentId;
 
-    const strippedAgentSource = stripMetaIdLines(agentSource);
-    if (strippedAgentSource !== agentSource) {
-        agentSource = strippedAgentSource;
-        agentProfile = parseAgentSource(agentSource);
-    }
+    agentSource = stripMetaIdLines(agentSource);
+    const sourceVisibility = parseAgentSourceVisibility(agentSource, { isStrict: true });
+    const resolvedVisibility =
+        options.isVisibilityOverride || !sourceVisibility
+            ? options.visibility ?? sourceVisibility ?? DEFAULT_AGENT_VISIBILITY
+            : sourceVisibility;
+
+    agentSource = setAgentSourceVisibility(agentSource, resolvedVisibility);
+
+    const agentProfile = parseAgentSource(agentSource);
+    const visibility = parseAgentSourceVisibility(agentSource, { isStrict: true }) ?? undefined;
 
     return {
         agentProfile,
         agentSource,
         permanentId,
+        visibility,
     };
 }
 

package/src/commands/KNOWLEDGE/utils/knowledgeSourceContentToName.ts

@@ -1,4 +1,4 @@
-import { SHA256 as sha256 } from 'crypto-js';
+import CryptoJS from 'crypto-js';
 import hexEncoder from 'crypto-js/enc-hex';
 import type { string_knowledge_source_content } from '../../../types/string_knowledge_source_content';
 import type { string_name } from '../../../types/string_name';
@@ -10,7 +10,7 @@ import { normalizeToKebabCase } from '../../../utils/normalization/normalize-to-
  * @public exported from `@promptbook/editable`
  */
 export function knowledgeSourceContentToName(knowledgeSourceContent: string_knowledge_source_content): string_name {
-    const hash = sha256(hexEncoder.parse(JSON.stringify(knowledgeSourceContent)))
+    const hash = CryptoJS.SHA256(hexEncoder.parse(JSON.stringify(knowledgeSourceContent)))
         //    <- TODO: [🥬] Encapsulate sha256 to some private utility function
         .toString(/* hex */)
         .substring(0, 20);

package/src/commitments/GOAL/GOAL.ts

@@ -101,8 +101,13 @@ export class GoalCommitmentDefinition extends BaseCommitmentDefinition<'GOAL' |
             return requirements;
         }
 
-        // Add goal as a proper h2 section to the system message
-        const goalSection = `## Goal\n\n${trimmedContent}`;
+        const goalSection = spaceTrim(
+            (block) => `
+                ## Goal
+
+                ${block(trimmedContent)}
+            `,
+        );
         const requirementsWithGoal = this.appendToSystemMessage(requirements, goalSection, '\n\n');
 
         return this.appendToPromptSuffix(requirementsWithGoal, trimmedContent);

package/src/commitments/LANGUAGE/LANGUAGE.ts

@@ -70,8 +70,13 @@ export class LanguageCommitmentDefinition extends BaseCommitmentDefinition<'LANG
             return requirements;
         }
 
-        // Add language as a bullet under a ## Language section
-        const languageSection = `## Language\n\n-   Your language is ${trimmedContent}`;
+        const languageSection = spaceTrim(
+            (block) => `
+                ## Language
+
+                -   Your language is ${block(trimmedContent)}
+            `,
+        );
 
         return this.appendToSystemMessage(requirements, languageSection, '\n\n');
     }