@riotprompt/riotprompt 0.0.1

package/dist/util/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sources":["../../src/util/text.ts"],"sourcesContent":["import { DEFAULT_CHARACTER_ENCODING } from \"../constants\";\n\n// Returns true if the input is likely text, false if likely binary\nexport function isText(input: string | Buffer): boolean {\n    let buf: Buffer;\n    if (typeof input === 'string') {\n        buf = Buffer.from(input, DEFAULT_CHARACTER_ENCODING);\n    } else {\n        buf = input;\n    }\n\n    // Empty buffers are considered text\n    if (buf.length === 0) {\n        return true;\n    }\n\n    // If the buffer contains null bytes, it's likely binary\n    if (buf.includes(0)) {\n        return false;\n    }\n\n    // For UTF-8 encoded text (including emoji and international characters),\n    // convert to string first and check if there are non-printable characters\n    const str = buf.toString(DEFAULT_CHARACTER_ENCODING);\n\n    // Count the number of non-printable ASCII characters (excluding common whitespace)\n    let nonPrintable = 0;\n    const len = Math.min(str.length, 512); // Only check the first 512 characters for performance\n\n    for (let i = 0; i < len; i++) {\n        const charCode = str.charCodeAt(i);\n        // Allow: tab (9), line feed (10), carriage return (13), printable ASCII (32-126)\n        // Also allow all non-ASCII Unicode characters (charCode > 127)\n        if (\n            charCode !== 9 && charCode !== 10 && charCode !== 13 &&\n            (charCode < 32 || (charCode > 126 && charCode < 128))\n        ) {\n            nonPrintable++;\n        }\n    }\n\n    // If more than 10% of the checked characters are non-printable, consider it binary\n    return nonPrintable / len < 0.1;\n}\n"],"names":["isText","input","buf","Buffer","from","DEFAULT_CHARACTER_ENCODING","length","includes","str","toString","nonPrintable","len","Math","min","i","charCode","charCodeAt"],"mappings":";;AAEA;AACO,SAASA,OAAOC,KAAsB,EAAA;IACzC,IAAIC,GAAAA;IACJ,IAAI,OAAOD,UAAU,QAAU,EAAA;QAC3BC,GAAMC,GAAAA,MAAAA,CAAOC,IAAI,CAACH,KAAOI,EAAAA,0BAAAA,CAAAA;KACtB,MAAA;QACHH,GAAMD,GAAAA,KAAAA;AACV;;IAGA,IAAIC,GAAAA,CAAII,MAAM,KAAK,CAAG,EAAA;QAClB,OAAO,IAAA;AACX;;IAGA,IAAIJ,GAAAA,CAAIK,QAAQ,CAAC,CAAI,CAAA,EAAA;QACjB,OAAO,KAAA;AACX;;;IAIA,MAAMC,GAAAA,GAAMN,GAAIO,CAAAA,QAAQ,CAACJ,0BAAAA,CAAAA;;AAGzB,IAAA,IAAIK,YAAe,GAAA,CAAA;IACnB,MAAMC,GAAAA,GAAMC,KAAKC,GAAG,CAACL,IAAIF,MAAM,EAAE;AAEjC,IAAA,IAAK,IAAIQ,CAAAA,GAAI,CAAGA,EAAAA,CAAAA,GAAIH,KAAKG,CAAK,EAAA,CAAA;QAC1B,MAAMC,QAAAA,GAAWP,GAAIQ,CAAAA,UAAU,CAACF,CAAAA,CAAAA;;;AAGhC,QAAA,IACIC,QAAa,KAAA,CAAA,IAAKA,QAAa,KAAA,EAAA,IAAMA,QAAa,KAAA,EAAA,KACjDA,QAAAA,GAAW,EAAOA,IAAAA,QAAAA,GAAW,GAAOA,IAAAA,QAAAA,GAAW,GAAG,CACrD,EAAA;AACEL,YAAAA,YAAAA,EAAAA;AACJ;AACJ;;AAGA,IAAA,OAAOA,eAAeC,GAAM,GAAA,GAAA;AAChC;;;;"}

package/docs/loader.md

@@ -0,0 +1,237 @@
+# riotprompt Loader Utility
+
+## Overview
+
+The **Loader** utility in riotprompt is designed to import prompt content from the filesystem. It can take a directory (or multiple directories) of Markdown files and convert them into riotprompt sections or items. This is especially useful for managing large or modular prompt structures, where different parts of the prompt (personas, instructions, context, etc.) are kept in separate files for clarity and reusability.
+
+By using the Loader, you can:
+
+* **Organize Prompts as Files**: Keep complex prompts as separate markdown files (e.g., one file per persona, or per context topic).
+* **Reuse Content**: Share and reuse prompt segments across projects by simply loading the files.
+* **Keep Code and Prompts Separate**: Your application code can load prompt content at runtime, making it easier to update prompts without changing code.
+* **Scale to Many Context Files**: Effortlessly include a large number of context snippets or knowledge base files as part of the prompt by placing them in a context directory and loading them all.
+
+> **NOTE:** This was originally designed to support loading context from a directory of Markdown files. For example, if you are analyzing emails, you might want to have a directory named "./context/projects" that contains a series of Markdown files that give context about different projects.
+
+
+## How the Loader Transforms Files
+
+The Loader works together with the Parser under the hood. When you point the Loader at a directory, it will:
+
+1. **Scan the Directory**: It finds all files in the specified directory (not including subdirectories). The Loader is agnostic about file extensions and processes all files in the directory.
+2. **Read each File**: For each file found, the Loader reads its content from disk.
+3. **Parse Content into Sections**: If any of the files are Markdown (ending in .md), the Loader uses the Parser to convert the Markdown content of the file into a Section (or items). Crucially, the Loader will strip out the first heading from the file from the content and use it as the section title if a heading is present. If a particular file does not contain Markdown, a section will be added for the file with the name of the file as the Section title.
+
+   * If the file content begins with a heading (e.g., `# Title`), that heading is used as the Section's title and is not duplicated in the Section's items.
+   * The rest of the file's content becomes the body (items) of that Section.
+   * If a file does not contain an explicit top-level heading, the Loader can optionally use the filename (or a provided default) as the section title, or simply treat all content as belonging to an unnamed section.
+4. **Aggregate or Return Sections**: The Loader then returns the structured content from all files. You can choose to combine these sections into a larger Section (for example, a single "Context" section containing multiple subsections), or handle them individually.
+
+This approach means you can, for example, have a directory of background context files and load them all at once, without manually copying and pasting their content into one big prompt string.
+
+## Using the Loader
+
+Typically, you'll create a Loader instance via its factory method and then call methods to load files or directories. For example:
+
+```ts
+import { Loader, Section } from '@riotprompt';
+
+// Create a Loader instance
+const loader = Loader.create();
+
+// Load all markdown files from a directory (e.g., the "context" folder)
+const contextSections: Section<Context>[] = await loader.load<Context>(['./prompts/context']);
+
+// contextSections is an array of Section objects, one per markdown file in the directory.
+console.log(`Loaded ${contextSections.length} context sections.`);
+```
+
+In this snippet, `loader.load<Context>(['./prompts/context'])` will find all markdown files under `./prompts/context`. Suppose the folder structure is:
+
+```
+prompts/
+  context/
+    project-alpha.md
+    project-beta.md
+```
+
+And the files contain:
+
+* **project-alpha.md**:
+
+  ```
+  # Project Alpha
+
+  Details about Project Alpha...
+  ```
+
+* **project-beta.md**:
+
+  ```
+  # Project Beta
+
+  Information on Project Beta...
+  ```
+
+After running the loader:
+
+* `contextSections[0]` will be a Section titled "Project Alpha", containing the text "Details about Project Alpha..." as its content (as an item in that section).
+* `contextSections[1]` will be a Section titled "Project Beta", with "Information on Project Beta..." as its content.
+
+Each file became its own Section, using the first line header as the title.
+
+### Loading Multiple Directories or Mixed Content
+
+You can call `load` multiple times or even use Loader methods to load individual files. The riotprompt **Builder** provides higher-level methods (like `loadContext` or `loadContent`) which can take an array of directories or file paths and internally use the Loader to gather them.
+
+For example, using the Builder (which internally leverages the Loader):
+
+```ts
+import { Builder, Prompt } from '@riotprompt';
+
+const builder = Builder.create({
+  basePath: './prompts'
+});
+const prompt: Prompt = await builder
+  .addInstructionPath('instructions/code-review.md')
+  .loadContext(['./prompts/context', './prompts/additional-context'])
+  .build();
+```
+
+In this example, `builder.loadContext([...])` will use the Loader to load all Markdown files from the two specified directories (`./prompts/context` and `./prompts/additional-context`), combining them appropriately into the prompt's context section. You don't have to manually instantiate `Loader` here because `Builder` does it for you.
+
+However, if you want fine-grained control, you can use `Loader` directly. For instance, you might want to load a directory of context files, filter or modify them, and then insert them into different parts of the prompt.
+
+> NOTE: The Builder example above uses a single `basePath` for simplicity. In most real-world use cases, you'll likely want to include an `overridePath` as well, which allows for customization of prompts without modifying the original files.
+
+
+**Example – Direct Loader usage:**
+
+```ts
+const loader = Loader.create();
+// Load persona definitions from a directory
+const personaSections: Section<Instruction>[] = await loader.load<Instruction>(['./prompts/personas']);
+// Load context files from multiple directories
+const peopleContext: Section<Context>[] = await loader.load<Context>(['./prompts/context/people']);
+const projectContext: Section<Context>[] = await loader.load<Context>(['./prompts/context/projects']);
+
+// You can now, for example, combine these:
+const combinedContext = createSection<Context>("Context");
+for (const sec of [...peopleContext, ...projectContext]) {
+  combinedContext.add(sec);
+}
+```
+
+In this example, we manually loaded personas and context from different folders and then merged the context sections into a single Section called "Context". (Note: riotprompt might provide utility methods for combining sections, but doing it manually as shown is also straightforward.)
+
+### Example Folder Structure
+
+To illustrate a larger setup, imagine your `./prompts` directory is organized as follows:
+
+```
+prompts/
+  personas/
+    developer.md
+    manager.md
+  instructions/
+    code-review.md
+    summarize.md
+  content/
+    example-request.md
+  context/
+    project/
+      alpha.md
+      beta.md
+    team/
+      team-info.md
+```
+
+* **Personas** directory contains persona profiles (e.g., "developer" persona, "manager" persona).
+* **Instructions** directory contains different sets of instructions (for different tasks like code review, summarization).
+* **Content** might contain user prompts or example content pieces.
+* **Context** is further divided into subfolders (e.g., project-specific context files, team info files).
+
+Using Loader (via Builder or directly), you can easily load all relevant pieces:
+
+* `loader.load<Instruction>(['./prompts/personas'])` yields an array of persona Sections.
+* `loader.load<Instruction>(['./prompts/instructions'])` yields Sections for each set of instructions.
+* `loader.load<Context>(['./prompts/context/project'])` and `loader.load<Context>(['./prompts/context/team'])` yield context Sections which you might then combine.
+
+
+
+### Loader Options
+
+The Loader's `create` method may allow some configuration as well. Common configurations include:
+
+* **File Extensions**: The Loader is agnostic about file extensions and will include all files in the specified directory. There is one special file, `content.md`, which is parsed first and supplies instructions for the section that will contain sections for each of the included files. Additionally, any file with a `.md` extension will have its first header parsed to set the title of the resulting Section. You do not need to configure file extensions; the Loader handles all files appropriately based on their extension.
+* **Non-Recursive Directory Scanning**: The `load()` method only processes files in the immediate directories specified in the array. It does not automatically traverse subdirectories. If you need to process files in subdirectories, you must explicitly include those subdirectory paths in the array passed to `load()`. For example, to load files from both `./prompts/context/project` and `./prompts/context/team`, you would need to call `load(['./prompts/context/project', './prompts/context/team'])`.
+* **Ignore Patterns**: You can provide an array of regular expression strings via the `ignorePatterns` option in the `Options` interface. Files matching any of these patterns will be excluded from processing. This is useful for ignoring hidden files, temporary files, or specific file types you don't want to load. By default, the Loader uses the following patterns to ignore common non-content files:
+    * `^\\..*`: Ignores hidden files (e.g., `.git`, `.DS_Store`).
+    * `\\.(jpg|jpeg|png|gif|bmp|svg|webp|ico)$`: Ignores common image file extensions.
+    * `\\.(mp3|wav|ogg|aac|flac)$`: Ignores common audio file extensions.
+    * `\\.(mp4|mov|avi|mkv|webm)$`: Ignores common video file extensions.
+    * `\\.(pdf|doc|docx|xls|xlsx|ppt|pptx)$`: Ignores common document file formats that are typically binary.
+    * `\\.(zip|tar|gz|rar|7z)$`: Ignores common compressed file extensions.
+  You can override these defaults by passing your own array of regex strings to `ignorePatterns`.
+* **Parameters**: Similar to the Parser, the Loader might accept a `Parameters` object if you want to substitute placeholders in all loaded files. Another approach is to pass `parameters` into the Builder (so that after loading, when formatting, those parameters are applied).
+
+### Parameterized Content Loading
+
+The Loader supports parameterized content through the `parameters` option in the `Options` interface. This allows you to define variables in your markdown files and have them replaced with actual values when the content is loaded.
+
+Here's how to use this feature:
+
+```ts
+import { Loader, Section } from '@riotprompt';
+
+// Create a Loader with parameters
+const loader = Loader.create({
+  parameters: {
+    projectName: "Alpha Project",
+    clientName: "Acme Corporation",
+    deadline: "December 31, 2023"
+  }
+});
+
+// Load content that contains variables
+const contextSections: Section<Context>[] = await loader.load<Context>(['./prompts/context']);
+```
+
+In this example, any markdown file in the `./prompts/context` directory can include variables like `{{projectName}}`, `{{clientName}}`, or `{{deadline}}`, and they will be replaced with the corresponding values when loaded.
+
+For instance, if one of your files contains:
+
+```markdown
+# {{projectName}} Overview
+
+This document provides key information about {{projectName}} for {{clientName}}.
+The project has a delivery deadline of {{deadline}}.
+```
+
+After loading, this content would be transformed to:
+
+```markdown
+# Alpha Project Overview
+
+This document provides key information about Alpha Project for Acme Corporation.
+The project has a delivery deadline of December 31, 2023.
+```
+
+This parameterization feature is extremely useful for:
+
+* Creating reusable template prompts
+* Injecting dynamic values into your prompts at runtime
+* Maintaining a single source of truth for key information across multiple prompt files
+
+You can change the parameters for each Loader instance, allowing you to generate different versions of the same prompt templates for different scenarios.
+
+### Purpose and Best Practices
+
+Using Loader helps manage large prompts by breaking them into maintainable pieces:
+
+* **Separation of Concerns**: Keep each logical part of the prompt in its own file (e.g., persona definitions, instructional prompts, background context). This makes editing and reviewing prompts easier.
+* **Dynamic Inclusion**: You can decide at runtime which files or directories to load. For instance, load different instruction sets based on user input or context (by pointing Loader to different folders).
+* **Reusability**: If multiple applications or multiple parts of your application need the same prompt content, having them in files that the Loader can pull in avoids duplication in code.
+
+In summary, the Loader utility bridges the gap between your prompt files on disk and the in-memory structures that riotprompt uses. It handles the heavy lifting of reading files and parsing Markdown, so you can assemble your final prompt by simply organizing files and calling load functions. This results in a cleaner project structure and easier prompt maintenance.
+

package/docs/override.md

@@ -0,0 +1,323 @@
+# riotprompt Override Utility
+
+## Overview
+
+The **Override** utility in riotprompt allows you to customize or replace parts of a prompt without altering the original prompt files. This is particularly useful in larger applications or frameworks (like Cortalyne) where you have default prompt templates but want to adjust certain sections for specific use cases, users, or environments. By using overrides, you can maintain a clean separation between **core prompt content** and **custom modifications**.
+
+In essence, overrides let you **selectively replace or augment prompt sections**:
+
+* You can completely **override** a section (replace it entirely with new content).
+* You can **prepend** content (insert additional text before the original content).
+* You can **append** content (insert additional text after the original content).
+
+All of this is done without modifying the original prompt source file; instead, riotprompt will detect override files and merge or replace content accordingly when building the final prompt.
+
+## How Overrides Work
+
+riotprompt's override system works by looking for specially-named files in an "override" directory that correspond to your prompt files. When you build a prompt (for example, using the Builder), you can specify an `overridePath` where your override files live and enable overrides.
+
+For each prompt file loaded from the base path, riotprompt will check if there is a corresponding override file. The correspondence is determined by **filename and path**:
+
+* If an override file with the *exact same name* exists in the override directory (mirroring the relative path of the original file), riotprompt will treat that as a **full override** for that prompt file.
+* Additionally, riotprompt recognizes two suffix conventions for partial overrides:
+
+  * A file ending in **`-pre.md`** is treated as content to **prepend** (placed before the base content).
+  * A file ending in **`-post.md`** is treated as content to **append** (placed after the base content).
+
+This naming scheme allows you to choose the override mode by how you name the file, without needing additional configuration in code for each file.
+
+**Example:**
+
+Suppose you have a base prompt file `prompts/instructions/email.md` that defines instructions for drafting an email. To modify this via overrides:
+
+* Place a file at `overrides/instructions/email.md` – this will completely replace the content of `email.md` when overrides are applied.
+* Place a file at `overrides/instructions/email-pre.md` – this will be inserted *before* the content of the base `email.md`.
+* Place a file at `overrides/instructions/email-post.md` – this will be inserted *after* the content of the base `email.md`.
+
+You can use none, one, or all of these in combination as needed. For instance, you might only have a `email-post.md` to add a few extra instructions at the end of the default email instructions, leaving the original content intact.
+
+## Note on Path Configuration
+
+When implementing overrides in a real-world application, the paths are often configured strategically:
+
+* **basePath** is frequently constructed to point to content from a package, often using variables like `__dirname` to reference the location of the installed package. For example:
+
+  ```ts
+  import path from 'path';
+  import { fileURLToPath } from 'url';
+
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+
+  const basePath = path.join(__dirname, '../prompts');
+  ```
+
+* **overridePath** is typically configured using a project's configuration directory, which might be in the user's workspace or a designated config location:
+
+  ```ts
+  const overridePath = path.join(process.cwd(), 'config/prompts');
+  ```
+
+This setup creates a powerful pattern where library authors can ship applications with a set of default prompts (in the package's prompts directory), while allowing users to customize those prompts by:
+
+1. **Completely replacing** prompt content by providing override files with the same name
+2. **Extending** the default prompts by adding content before or after using the `-pre.md` and `-post.md` conventions
+
+This approach maintains a clean separation between the library's default content and user customizations, making it easier to update the library without losing custom modifications. It's particularly valuable in frameworks and tools that rely heavily on prompt engineering but need to support user-specific adaptations.
+
+**Directory Structure:**
+
+The override directory should mirror the structure of the base prompt directory. For example:
+
+```
+prompts/                 (base prompt files)
+  instructions/
+    email.md
+    meeting.md
+
+overrides/               (override files)
+  instructions/
+    email-pre.md      (prepends content to email.md instructions)
+    email-post.md     (appends content to email.md instructions)
+    meeting.md        (completely overrides meeting.md instructions)
+```
+
+When a prompt is configured, the Builder and Override utility will take the paths "instructions/email.md" and "instructions/meeting.md", and the library will change the extension from ".md" to "-pre.md" and "-post.md" when it is looking for override content.
+
+In this scenario:
+
+* For `email.md`, the builder will find an `email-pre.md` and `email-post.md`. It will prepend and append their content around `email.md`'s content. There is no `email.md` full override in the overrides directory, so the base content is still used (with the additions).
+* For `meeting.md`, a full override file exists in overrides. That means the original `meeting.md` content will be entirely replaced by the content from the override file. (If there were also `meeting-pre.md` or `meeting-post.md`, those would be applied as well, but typically if you're fully overriding, you may not use pre/post for that file.)
+
+## Enabling Overrides in Builder
+
+If you are using the `Builder` to assemble prompts, you need to tell it to use the overrides. This is done via the `overridePath` and `overrides` options in `Builder.create()`:
+
+```ts
+const builder = Builder.create({
+  basePath: './prompts',
+  overridePath: './overrides',
+  overrides: true
+});
+```
+
+* `basePath` is where your base prompt files are located.
+* `overridePath` is where your override files are located.
+* `overrides: true` enables the override functionality. (By default, riotprompt might ignore override files unless this flag is set. This is a safety feature to prevent accidental override of content.)
+
+When `overrides` is true, the builder will incorporate any found override files as it loads prompt files. If you set an override path but `overrides` is false (or omitted), riotprompt will likely skip applying full overrides. (Prepend/append might still be applied, or they might also be ignored – typically you enable the flag when you intend to use any overrides.)
+
+In applications like **Cortalyne**, a command-line flag is used (e.g. `--overrides`) to toggle this behavior. This maps to the `overrides: true` setting in the riotprompt builder.
+
+## Using Override Utility Programmatically
+
+While the common usage is via Builder configuration, riotprompt also provides lower-level capabilities to apply overrides if needed.
+
+For example, there may be an `Override` class or methods that you can use on Section objects:
+
+```ts
+import { Override, createSection } from '@riotprompt';
+
+// Suppose we have a base section created or loaded:
+const baseSection = createSection("Instructions");
+baseSection.add("Follow the company style guide.");
+baseSection.add("Keep the email concise.");
+
+// Create an Override instance
+const override = Override.create({
+  configDir: './overrides',
+  overrides: true
+});
+
+// Customize the section using an override file path
+await override.customize('instructions/email.md', baseSection);
+
+// Now baseSection might have content prepended, appended, or completely replaced
+// depending on what override files exist in the './overrides' directory:
+// - ./overrides/instructions/email.md (full override)
+// - ./overrides/instructions/email-pre.md (prepend)
+// - ./overrides/instructions/email-post.md (append)
+
+console.log(baseSection.items[0].text);
+// Output depends on what override files exist
+```
+
+In this example, `override.customize` takes a file path string ('instructions/email.md'), a section object (baseSection), and optionally section options. Under the hood, this is what Builder would do when it finds override files.
+
+Even if you don't call `Override` methods directly, understanding this helps – basically riotprompt will inject the override content at the appropriate place.
+
+## Guidance for Structuring Overrides
+
+When using overrides in your project, consider the following best practices:
+
+* **Mirror File Structure**: Keep the override files in a parallel structure to the base prompt files. This makes it clear which base file each override is targeting. For example, if the base has `personas/agent.md`, put the override in `overrides/personas/agent.md` (or `agent-pre.md`/`agent-post.md` as needed).
+* **Minimize Full Overrides**: Whenever possible, use prepend (`-pre.md`) or append (`-post.md`) files to adjust content, rather than completely overriding. Prepending/appending is less likely to break core functionality because you are adding to the existing prompt rather than replacing it. Use a full override (`same-name.md`) only when you need to substantially change or replace the entire content.
+* **Use Overrides for Environment-Specific Tweaks**: If you have multiple deployment environments or user customizations, you can maintain different override directories or files for each case. For example, one override file could tweak the tone of instructions for a specific client without affecting the base prompt shared by others.
+* **Test Overrides Thoroughly**: Because overrides can change the behavior of prompts, test with and without overrides enabled (if your app allows). Tools like Cortalyne have a debug mode to show final prompts after overrides – use that to ensure your override content is merging correctly.
+* **Document Your Overrides**: Within your team or project, document what each override file is intended to do. Since they change default behavior, it's good to have a note (even within the file as a comment) about why the override exists.
+
+## Example: Combining Base and Override Content
+
+Let's walk through a concrete example. Imagine a base persona file `prompts/personas/assistant.md`:
+
+```markdown
+# Assistant Persona
+- You are a helpful assistant with expertise in marketing.
+- Your tone is friendly and professional.
+```
+
+Now suppose for a specific scenario we want the assistant to adopt a more formal tone, but we don't want to change the base file (since that is the default for other scenarios). We create an override file `overrides/personas/assistant-pre.md` with:
+
+```markdown
+- (Formal Override) Your tone is formal and courteous.
+```
+
+We also create `overrides/personas/assistant-post.md` with:
+
+```markdown
+- Always adhere to corporate communication guidelines.
+```
+
+We run our builder with overrides enabled. What happens?
+
+* riotprompt loads the base `assistant.md` persona Section:
+
+  * Title: "Assistant Persona"
+  * Items:
+
+    1. "You are a helpful assistant with expertise in marketing."
+    2. "Your tone is friendly and professional."
+* It finds `assistant-pre.md` and `assistant-post.md` in overrides for that path.
+* The content from `assistant-pre.md` ("Your tone is formal and courteous.") is inserted at the **beginning** of the assistant persona's items (before the original items).
+* The content from `assistant-post.md` ("Always adhere to corporate communication guidelines.") is inserted at the **end** of the items list.
+* The resulting Section "Assistant Persona" now has:
+
+  1. "(Formal Override) Your tone is formal and courteous."
+  2. "You are a helpful assistant with expertise in marketing."
+  3. "Your tone is friendly and professional."
+  4. "Always adhere to corporate communication guidelines."
+
+Notice how the original content was not removed – we only added to it in this case. If we had provided an `assistant.md` in the override directory (a full override), then none of the original items would be kept (they would be replaced entirely by whatever is in that override file).
+
+This mechanism is powerful for tweaking behavior on the fly.
+
+## Using Parameters with Overrides
+
+The Override utility supports dynamic content customization through parameters. Parameters allow you to define placeholders in your prompt text (e.g., `{{variable}}`) that get replaced with specific values when the prompt is processed. This creates even more flexibility in your override files.
+
+### Example: Dynamic Overrides with Parameters
+
+Consider a scenario where you want to customize a chatbot persona for different clients while maintaining a consistent base structure. You can use parameters in your override files to achieve this:
+
+```ts
+import { Override, createSection, createParameters } from '@riotprompt';
+
+// Create a base assistant persona
+const assistantPersona = createSection("Assistant Persona");
+assistantPersona.add("You are a helpful customer service AI.");
+assistantPersona.add("You provide clear, accurate information.");
+
+// Create parameters for client-specific customization
+const clientParameters = createParameters({
+  clientName: "Acme Corporation",
+  industry: "manufacturing",
+  supportEmail: "support@acme.com"
+});
+
+// Create an override instance with parameters
+const override = Override.create({
+  configDir: './overrides',
+  overrides: true,
+  parameters: clientParameters
+});
+
+// Apply client-specific overrides with parameter substitution
+await override.customize('personas/assistant.md', assistantPersona);
+```
+
+Now in your override file `./overrides/personas/assistant-post.md`, you can use those parameters:
+
+```markdown
+- You are assisting {{clientName}}, a company in the {{industry}} industry.
+- For additional support, direct customers to {{supportEmail}}.
+```
+
+When processed, the placeholders will be replaced with the actual values provided in the parameters, resulting in:
+
+```
+# Assistant Persona
+- You are a helpful customer service AI.
+- You provide clear, accurate information.
+- You are assisting Acme Corporation, a company in the manufacturing industry.
+- For additional support, direct customers to support@acme.com.
+```
+
+This approach allows you to:
+1. Maintain a clean separation between core prompt content and customizations
+2. Dynamically update client-specific information without editing the override files
+3. Reuse the same override files with different parameter sets for various clients or environments
+
+When combined with environment variables or configuration files, this creates a powerful system for maintaining context-aware prompts that can be tailored for different scenarios without duplicating content.
+
+
+## Configuring Logging
+
+The Override utility supports custom logging to help debug override operations. When creating an Override instance, you can supply a `logger` property in the options:
+
+```ts
+import { Override, Logger } from '@riotprompt';
+
+// Create a custom logger
+const myLogger: Logger = {
+  debug: (message, ...args) => myCustomLogging.debug(message, args),
+  info: (message, ...args) => myCustomLogging.info(message, args),
+  warn: (message, ...args) => myCustomLogging.warn(message, args),
+  error: (message, ...args) => myCustomLogging.error(message, args),
+  verbose: (message, ...args) => myCustomLogging.verbose(message, args),
+  silly: (message, ...args) => myCustomLogging.silly(message, args)
+};
+
+// Use custom logger with Override
+const override = Override.create({
+  configDir: './overrides',
+  overrides: true,
+  logger: myLogger
+});
+```
+
+> **Note:** You don't have to create your own logger. This interface matches the default Winston logger interface, so you can directly use Winston loggers with riotprompt.
+
+The `Logger` interface requires six methods:
+
+```ts
+interface Logger {
+  debug: (message: string, ...args: any[]) => void;
+  info: (message: string, ...args: any[]) => void;
+  warn: (message: string, ...args: any[]) => void;
+  error: (message: string, ...args: any[]) => void;
+  verbose: (message: string, ...args: any[]) => void;
+  silly: (message: string, ...args: any[]) => void;
+}
+```
+
+If you don't provide a logger, riotprompt uses a default logger that maps these methods to the corresponding `console` methods (`console.debug`, `console.info`, etc.), with `verbose` and `silly` both mapping to `console.log`.
+
+The logger helps you track:
+- When override files are found
+- Which override files are being applied
+- When content is being prepended, appended, or replaced
+- The final content after all overrides are applied
+
+This is particularly useful during development and troubleshooting to understand exactly how your overrides are being applied to your prompt content.
+
+
+## Conclusion
+
+The Override utility makes riotprompt flexible and extensible:
+
+* It enables on-the-fly customization of prompt content.
+* It supports complex use cases like user-specific or context-specific prompt adjustments, all while keeping base prompts clean and general.
+* When building applications (like Cortalyne) on top of riotprompt, consider exposing an override mechanism to your end users or for your configurations. This way, you can ship a set of robust default prompts and still allow modifications without editing those core files.
+
+By following a consistent override pattern (filename matching and pre/post suffixes) and using the Builder's override support, you can manage prompt variations systematically and safely.
+