@promptbook/cli 0.113.0-9 → 0.114.0-0

package/src/book-2.0/book-language-documentation/BookLanguageManualDictionary.ts

@@ -0,0 +1,219 @@
+import type { string_language } from '../../types/string_token';
+
+/**
+ * One chapter of the standalone Book language manual.
+ *
+ * The heading anchors are intentionally **not** part of the dictionary, so deep
+ * links stay stable across languages.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type BookLanguageManualChapter = {
+    /**
+     * Translated chapter heading.
+     */
+    readonly title: string;
+
+    /**
+     * Translated chapter body as markdown.
+     */
+    readonly body: string;
+};
+
+/**
+ * Translated prose of one end-to-end example.
+ *
+ * The Book source of an example is language-neutral and therefore stays in
+ * `bookLanguageDocumentationExamples`.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type BookLanguageManualExampleText = {
+    /**
+     * Translated example heading.
+     */
+    readonly title: string;
+
+    /**
+     * Translated one-line goal of the example.
+     */
+    readonly goal: string;
+
+    /**
+     * Translated walkthrough steps explaining the example source.
+     */
+    readonly walkthrough: ReadonlyArray<string>;
+};
+
+/**
+ * One practical "don't vs do" pitfall item for Book language authoring.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type BookLanguageManualPitfall = {
+    /**
+     * Short pitfall title.
+     */
+    readonly title: string;
+
+    /**
+     * Description of what to avoid.
+     */
+    readonly dont: string;
+
+    /**
+     * Practical corrective action.
+     */
+    readonly doInstead: string;
+};
+
+/**
+ * Every translatable string of the standalone Book language manual.
+ *
+ * Commitment reference bodies are deliberately excluded, because they are the
+ * canonical English specification maintained next to each commitment in
+ * `src/commitments`.
+ *
+ * @private internal type of `createStandaloneBookLanguageMarkdown`
+ */
+export type BookLanguageManualDictionary = {
+    /**
+     * Language code this dictionary is written in.
+     */
+    readonly language: string_language;
+
+    /**
+     * Manual title used as the top-level heading.
+     */
+    readonly title: string;
+
+    /**
+     * Blockquote lines rendered directly under the manual title.
+     */
+    readonly introLines: ReadonlyArray<string>;
+
+    /**
+     * Labels of the generated manual metadata bullets.
+     */
+    readonly metadataLabels: {
+        readonly bookLanguageVersion: string;
+        readonly generatedAt: string;
+        readonly commitmentGroups: string;
+        readonly implementedCommitments: string;
+        readonly placeholderCommitments: string;
+    };
+
+    /**
+     * Heading of the table of contents.
+     */
+    readonly tableOfContentsTitle: string;
+
+    /**
+     * Chapters rendered in their canonical order.
+     */
+    readonly chapters: {
+        readonly whatIs: BookLanguageManualChapter;
+        readonly mentalModel: BookLanguageManualChapter;
+        readonly howToStructure: BookLanguageManualChapter;
+        readonly primitives: BookLanguageManualChapter;
+        readonly commitmentCatalog: BookLanguageManualChapter;
+        readonly examples: Pick<BookLanguageManualChapter, 'title'>;
+        readonly pitfalls: Pick<BookLanguageManualChapter, 'title'>;
+        readonly tutorial: BookLanguageManualChapter;
+        readonly lowLevelCommitments: BookLanguageManualChapter;
+    };
+
+    /**
+     * Sub-sections of the "Mental model of an agent" chapter.
+     */
+    readonly mentalModelSections: {
+        readonly detectedIntro: string;
+        readonly detectedProfileLabel: string;
+        readonly detectedBehaviorLabel: string;
+        readonly detectedToolingLabel: string;
+        readonly detectedCompositionLabel: string;
+        readonly meta: BookLanguageManualChapter;
+        readonly inheritance: BookLanguageManualChapter;
+        readonly composition: BookLanguageManualChapter;
+        readonly capabilities: BookLanguageManualChapter;
+    };
+
+    /**
+     * Sub-sections of the "Primitives and constructs reference" chapter.
+     */
+    readonly primitivesSections: {
+        readonly coreSyntax: BookLanguageManualChapter;
+        readonly references: BookLanguageManualChapter;
+        readonly keywordsTitle: string;
+    };
+
+    /**
+     * Suffixes distinguishing a server-specific catalog from the portable one.
+     */
+    readonly commitmentCatalogTitleSuffixes: {
+        readonly usedFirst: string;
+        readonly all: string;
+    };
+
+    /**
+     * Labels used in every commitment catalog entry.
+     */
+    readonly commitmentLabels: {
+        readonly status: string;
+        readonly aliases: string;
+        readonly semantics: string;
+        readonly typeSchema: string;
+        readonly blockSchema: string;
+        readonly lowLevelNotice: string;
+        readonly usage: string;
+        readonly usageOccurrence: string;
+        readonly usageOccurrences: string;
+        readonly statusImplemented: string;
+        readonly statusPlaceholder: string;
+        readonly noAliases: string;
+    };
+
+    /**
+     * Labels used by end-to-end example sections.
+     */
+    readonly exampleLabels: {
+        readonly commitmentsUsed: string;
+        readonly fullSource: string;
+        readonly goal: string;
+        readonly walkthrough: string;
+        readonly noCommitments: string;
+    };
+
+    /**
+     * Translated prose of the portable examples, keyed by example id.
+     */
+    readonly exampleTexts: Readonly<Record<string, BookLanguageManualExampleText>>;
+
+    /**
+     * Labels used by the "Do nots and common pitfalls" chapter.
+     */
+    readonly pitfallLabels: {
+        readonly dont: string;
+        readonly doInstead: string;
+    };
+
+    /**
+     * Translated pitfall entries.
+     */
+    readonly pitfalls: ReadonlyArray<BookLanguageManualPitfall>;
+
+    /**
+     * Closing parts of the "Build an agent from scratch" chapter.
+     */
+    readonly tutorialSections: {
+        readonly serverAgentsHint: string;
+        readonly templateIntro: string;
+        readonly checklistTitle: string;
+        readonly checklistBody: string;
+    };
+
+    /**
+     * Closing "Generated from" block of the manual.
+     */
+    readonly footer: BookLanguageManualChapter;
+};

package/src/book-2.0/book-language-documentation/bookLanguageDocumentationExamples.ts

@@ -5,15 +5,14 @@ import type { BookLanguageDocumentationExample } from './BookLanguageDocumentati
  * End-to-end examples used by the standalone Book language documentation.
  *
  * These are intentionally compact but complete, so they can be copy-pasted and
- * used as practical starting points.
+ * used as practical starting points. Their prose lives in the manual
+ * dictionaries, keyed by the `id` of each example.
  *
  * @private internal utility of `createStandaloneBookLanguageMarkdown`
  */
 export const bookLanguageDocumentationExamples: ReadonlyArray<BookLanguageDocumentationExample> = [
     {
         id: 'minimal-hello-world-agent',
-        title: 'Minimal hello-world agent',
-        goal: 'Create the smallest useful agent with identity and greeting.',
         source: spaceTrim(`
             Hello World Agent
 
@@ -21,17 +20,9 @@ export const bookLanguageDocumentationExamples: ReadonlyArray<BookLanguageDocume
             INITIAL MESSAGE Hello! I am ready to help.
             CLOSED
         `),
-        walkthrough: [
-            'The first line (`Hello World Agent`) is the agent name.',
-            '`GOAL` defines the effective role and profile text.',
-            '`INITIAL MESSAGE` sets a deterministic first message for a new chat.',
-            '`CLOSED` prevents conversational self-modification.',
-        ],
     },
     {
         id: 'tool-using-browser-search-agent',
-        title: 'Tool-using agent (Browser + Search engine)',
-        goal: 'Enable internet research with clear sourcing behavior.',
         source: spaceTrim(`
             Web Research Assistant
 
@@ -42,17 +33,9 @@ export const bookLanguageDocumentationExamples: ReadonlyArray<BookLanguageDocume
             RULE Include source links in your final answer.
             INITIAL MESSAGE Ask me what topic you want to research and how deep the report should be.
         `),
-        walkthrough: [
-            '`USE SEARCH ENGINE` provides web search tooling and optional search instructions.',
-            '`USE BROWSER` enables URL fetching and interactive browsing tools.',
-            '`RULE` commitments make reliability behavior explicit and repeatable.',
-            'This pattern is ideal for current-events and fact-checking agents.',
-        ],
     },
     {
         id: 'rule-and-knowledge-agent',
-        title: 'Agent with RULE and KNOWLEDGE',
-        goal: 'Ground responses in explicit constraints and curated sources.',
         source: spaceTrim(`
             Support Policy Assistant
 
@@ -63,17 +46,9 @@ export const bookLanguageDocumentationExamples: ReadonlyArray<BookLanguageDocume
             RULE Never invent legal or policy statements.
             INITIAL MESSAGE I can explain refund and support rules from provided knowledge.
         `),
-        walkthrough: [
-            '`KNOWLEDGE` may be inline text or an external URL/document.',
-            '`RULE` commitments define non-negotiable behavior constraints.',
-            'Combining both creates predictable, grounded policy responses.',
-            'Use this pattern for compliance, support, and internal procedures.',
-        ],
     },
     {
         id: 'memory-agent-with-long-term-memory',
-        title: 'MEMORY agent with long-term memory',
-        goal: 'Persist user preferences across conversations.',
         source: spaceTrim(`
             Customer Success Memory Agent
 
@@ -83,17 +58,9 @@ export const bookLanguageDocumentationExamples: ReadonlyArray<BookLanguageDocume
             RULE Never store secrets or sensitive data unless explicitly requested and allowed.
             INITIAL MESSAGE I can remember your setup and preferences for future sessions.
         `),
-        walkthrough: [
-            '`MEMORY` adds runtime memory tools and memory-specific system guidance.',
-            '`RULE` commitments narrow what should be remembered to reduce privacy risks.',
-            'In Agents Server, memory is runtime-backed and user-scoped.',
-            'Use this for assistants that must preserve context over time.',
-        ],
     },
     {
         id: 'use-project-and-wallet-integration-agent',
-        title: 'USE PROJECT and WALLET external integration',
-        goal: 'Work with GitHub repositories and wallet-backed credentials.',
         source: spaceTrim(`
             Repository Maintainer
 
@@ -104,17 +71,9 @@ export const bookLanguageDocumentationExamples: ReadonlyArray<BookLanguageDocume
             RULE Never reveal raw credentials in chat output.
             INITIAL MESSAGE I can inspect the repository and help you prepare PR-ready changes.
         `),
-        walkthrough: [
-            '`USE PROJECT` enables repository tools for listing, reading, editing files, and creating PRs.',
-            'Credentials are resolved from wallet records at runtime in Agents Server.',
-            '`WALLET` is kept here as a compatibility marker, but current Book 2.0 parsing treats it as deprecated/ignored.',
-            'In current runtime behavior, wallet-backed integrations are driven by commitments such as `USE PROJECT` and `USE EMAIL`.',
-        ],
     },
     {
         id: 'use-calendar-integration-agent',
-        title: 'USE CALENDAR integration',
-        goal: 'Coordinate meetings and schedules through a connected Google Calendar.',
         source: spaceTrim(`
             Calendar Assistant
 
@@ -124,17 +83,9 @@ export const bookLanguageDocumentationExamples: ReadonlyArray<BookLanguageDocume
             RULE Confirm destructive actions before deleting an event.
             INITIAL MESSAGE Tell me the meeting details and I will schedule it in your calendar.
         `),
-        walkthrough: [
-            '`USE CALENDAR` enables calendar tools for listing, reading, creating, updating, and deleting events.',
-            'The first calendar URL identifies which calendar integration should be used.',
-            '`SCOPES` can explicitly request required Google Calendar OAuth permissions.',
-            'Credentials are resolved from wallet-backed Google Calendar OAuth records at runtime in Agents Server.',
-        ],
     },
     {
         id: 'agents-team-example',
-        title: 'Agents TEAM (with in-book teammates)',
-        goal: 'Delegate sub-tasks to specialized teammates.',
         source: spaceTrim(`
             Team Manager
 
@@ -160,11 +111,5 @@ export const bookLanguageDocumentationExamples: ReadonlyArray<BookLanguageDocume
             RULE Estimate complexity and identify blockers.
             CLOSED
         `),
-        walkthrough: [
-            'The main agent delegates via `TEAM` commitment.',
-            'References in `{...}` are resolved against embedded agents inside the same book (split by `---`).',
-            'Each teammate can be isolated with `FROM VOID` for deterministic specialization.',
-            'This pattern works well for multi-role review and decision support.',
-        ],
     },
 ];