Template System Overview

StudioBrain is a schema-driven platform. Every entity type — characters, locations, items, recipes, plants, tracks, episodes — is defined by a template: a Markdown file with YAML frontmatter that declares the entity’s fields, validation rules, and rendering behavior. Templates are the nouns of StudioBrain; tools are the verbs that operate on them.

What Is a Template?

A template is a Markdown file (typically *_TEMPLATE.md) whose YAML frontmatter declares:

• entity_type — the machine name (e.g. character, biome, recipe)
• template_category — how the template renders (entity, document, map, rule, skill)
• fields — a list of typed field definitions (string, text, integer, select, relation, etc.)
• display_name, description, icon — presentation metadata
• folder_name, file_prefix — where instances of this entity are stored on disk
• template_version — version string for update notifications

The body of the Markdown file (below the frontmatter) provides default content, documentation, or generation prompts for AI.

Minimal Example

---
entity_type: recipe
template_category: entity
display_name: Recipe
description: A cooking recipe with ingredients and steps
icon: utensils
folder_name: Recipes
file_prefix: RECIPE
template_version: "1.0"
fields:
  - name: cuisine
    type: select
    options: [Italian, Mexican, Japanese, French, Indian, American, Thai, Other]
    required: true
  - name: prep_time
    type: string
    label: Prep Time
  - name: ingredients
    type: text
    label: Ingredients
  - name: steps
    type: text
    label: Steps
---
 
# Recipe Template
 
Use this template for cooking recipes. The AI will generate ingredients
and step-by-step instructions based on the cuisine and any notes you provide.

When a user creates a new Recipe entity, StudioBrain reads this template and renders a form with the declared fields. The entity instance is saved as a Markdown file in the Recipes/ folder with RECIPE_ as the filename prefix.

Template Categories

The template_category field determines how StudioBrain renders and interacts with entities of that type. There are five categories:

Project Directory Structure

A StudioBrain project is a regular folder on disk. Directories prefixed with an underscore (_) are system directories managed by the application. Directories without the underscore prefix contain user entity data. A hidden .studiobrain/ directory holds local metadata that is not synced or version-controlled.

MyProject/
  .studiobrain/          # Hidden local metadata (gitignored, not synced)
    content.db           # SQLite entity index cache
    settings.json        # Per-project settings
    cache_state.db       # Sync and scan state
  _Templates/
    Core/               # Built-in base templates (read-only, auto-updated)
    Standard/           # Templates from catalog, packs, or marketplace
      CHARACTER_TEMPLATE.md
      LOCATION_TEMPLATE.md
      BIOME_TEMPLATE.md
      Documents/        # Document templates
        STYLE_GUIDE_TEMPLATE.md
        GDD_TEMPLATE.md
      Maps/             # Map templates
        WORLD_MAP_MAP_TEMPLATE.md
        DUNGEON_MAP_MAP_TEMPLATE.md
    Custom/             # User overrides (highest priority)
    Packs/              # Installable template packs
    Layouts/            # UI layout definitions (JSON)
  _Rules/
    Core/               # Built-in rules (read-only)
    Standard/           # Structured YAML rules from catalog
    Custom/             # User rule overrides (highest priority)
  _Skills/
    Core/               # Built-in skills (read-only)
    Standard/           # AI skill definitions from catalog
    Custom/             # User skill overrides (highest priority)
  _Plugins/             # Installed plugins
  _Archive/             # Archived entities
  _Generated/           # AI-generated output staging area
  Characters/           # Entity data folder (matches folder_name from template)
  Locations/
  Biomes/
  Recipes/

Override Priority

For templates, rules, and skills, StudioBrain resolves files using a layered priority system. The last match wins:

Core → Standard → Custom

• _Templates/Core/ contains built-in base templates that ship with StudioBrain. These are read-only and updated automatically.
• _Templates/Standard/ contains templates installed from packs, the catalog, or the marketplace. These can be updated via CatalogSync.
• _Templates/Custom/ contains your project-specific overrides. A Custom file with the same entity_type completely replaces the Standard or Core version.

The same pattern applies to _Rules/ and _Skills/. See Inheritance & Overrides for the full resolution algorithm.

Naming Conventions

• Template files: {ENTITY_TYPE}_TEMPLATE.md (e.g. CHARACTER_TEMPLATE.md)
• Document templates: {TYPE}_TEMPLATE.md in Standard/Documents/
• Map templates: {TYPE}_MAP_TEMPLATE.md in Standard/Maps/
• Entity data files: {FILE_PREFIX}_{entity_name}.md in {folder_name}/
• Layout files: {entity_type}.layout.json in Layouts/

How Templates Drive Entity Types

The entity_type field in a template’s frontmatter is the primary key that connects templates to the entity system:

1. Discovery — On startup, StudioBrain scans _Templates/ directories (and the catalog cache) for *_TEMPLATE.md files. Each file’s entity_type is registered.
2. Schema generation — The fields list in frontmatter is parsed into a typed schema. Field types map to UI components: string to text input, select to dropdown, text to textarea, relation to entity picker, etc.
3. Form rendering — When a user creates or edits an entity, the schema drives the form layout. If a layout definition exists for that entity type, it controls section ordering, tabs, and component blocks.
4. Storage — Entity instances are saved as Markdown files in the directory specified by folder_name, with filenames prefixed by file_prefix.
5. AI generation — When generating content for an entity, StudioBrain passes the template’s body text and any applicable rules and skills to the AI.

Field Types

Templates declare fields with a type property. The following field types are supported:

Fields support additional properties: required, default, label, description, min, max, options, and group (for layout grouping).

Next Steps

• Inheritance & Overrides — How template resolution works across Standard, Custom, and User layers
• AI Generation Rules — Constraints that guide AI content generation
• Agent Skills — AI capability definitions with prompts and parameters
• UI Layouts — JSON layout files that control entity page structure
• Template Packs — Bundled sets of templates for quick project setup
• Example: Biome Entity — A walkthrough of a real entity type