Template Inheritance & Custom Overrides

StudioBrain resolves templates through a layered system where more specific definitions override more general ones. This lets the platform ship sensible defaults while giving users full control over their entity schemas.

Resolution Order

When StudioBrain needs the template for an entity type (e.g. character), it checks multiple sources in order. The last match wins — later layers override earlier ones.

Catalog (studiobrain-templates repo)
  └── Core (_Templates/Core/)       ← built-in, read-only
        └── Standard (_Templates/Standard/)  ← from packs/catalog
              └── Custom (_Templates/Custom/)      ← your overrides
                    └── User (inline frontmatter overrides)

Layer	Source	Purpose	Who Manages
Catalog	`studiobrain-templates` GitHub repo, synced via CatalogSync	Curated official templates from Biloxi Studios	Biloxi Studios
Core	`_Templates/Core/` in the project	Built-in base templates (read-only, auto-updated)	System
Standard	`_Templates/Standard/` in the project	Templates installed from packs or the catalog	System / marketplace
Custom	`_Templates/Custom/` in the project	User overrides for any Standard or Core template	User
User	Inline frontmatter on individual entity files	Per-entity field overrides	User

How Overrides Work

To override a template, create a file with the same entity_type in a higher-priority directory. For example, to customize the Character template:

The catalog provides CHARACTER_TEMPLATE.md with fields like name, age, backstory, traits.
CatalogSync copies it into _Templates/Standard/CHARACTER_TEMPLATE.md.
You create _Templates/Custom/CHARACTER_TEMPLATE.md with your version — perhaps adding a faction field and removing age.
StudioBrain uses your Custom version because Custom takes precedence over Standard.

You only need to include the fields you want in your Custom override. The override replaces the entire template definition for that entity type — it does not merge fields from multiple layers.

User-Level Overrides

Individual entity files can override specific template fields in their own frontmatter. This is useful for one-off entities that need extra fields without changing the template for all entities of that type.

---
entity_type: character
name: Kira Volkov
# Extra field not in the template:
military_rank: Commander
---

The extra military_rank field is stored and displayed alongside the template-defined fields. It does not affect other Character entities.

Template Versioning

Templates include a template_version field in their frontmatter:

template_version: "2.1"

When CatalogSync pulls an updated template from the catalog, StudioBrain compares the version against the locally installed copy. If the catalog version is newer, a notification appears in the UI prompting the user to update. Updates never happen automatically — the user must accept the new version.

⚠️

Accepting a template version update overwrites the Standard version. If you have a Custom override in _Templates/Custom/, it continues to take precedence and the update has no visible effect until you remove or update your Custom version.

Cloud Edition: DB-Backed Resolution

StudioBrain Cloud only. Core uses filesystem-only resolution as described above. The database layer below is added by the cloud extension and does not exist in core.

On StudioBrain Cloud (multi-tenant SaaS), template resolution adds a database layer above the filesystem:

DB tenant override (per-tenant customization)
  └── DB system templates (catalog entries in database)
        └── Filesystem (same Standard/Core/Custom/User layers)

Layer	Source	Scope
DB tenant override	`template_entities` table, scoped by tenant	Per-team / per-project
DB system	`template_entities` table, system-wide	All tenants
Filesystem	Standard/Core/Custom directories	Fallback when DB has no entry

Cloud users interact with templates through the UI exactly the same way. The database layer is transparent — it exists so that multi-tenant deployments can store per-team customizations without filesystem access.

CatalogSync

CatalogSync is the service that pulls templates, rules, skills, layouts, and plugins from the studiobrain-templates GitHub repository into the local project.

How It Works

On startup, CatalogSync clones (or pulls) the studiobrain-templates repo into ~/.studiobrain/catalog/.
It creates symlinks from _Templates/Standard/ and _Rules/ to the cached catalog directories, so the template discovery system finds catalog content at the paths it expects.
A background task refreshes the catalog every 1 hour (configurable via the start_periodic_sync interval).
New or updated templates, rules, skills, and layouts are upserted into the marketplace registry database.

What Gets Synced

Content Type	Catalog Path	Discovery Method
Entity templates	`templates/Standard/*.md`	Scan for `*_TEMPLATE.md` with YAML frontmatter
Document templates	`templates/Standard/Documents/*.md`	Same scan, `template_category: document`
Map templates	`templates/Standard/Maps/*.md`	Same scan, `template_category: map`
Layouts	`templates/Layouts/*.layout.json`	Scan for `*.layout.json`
Rules	`rules/_RULES.md` and `rules/Standard/.yaml`	Scan for both Markdown and YAML formats
Skills	`skills/.yaml` and `skills/Standard/.yaml`	Scan for YAML files with `skill_id` field
Plugins	`plugins/*/plugin.json`	Scan for directories with `plugin.json` manifests

Community Content

Community-contributed content comes from the separate studiobrain-community-plugins repository. CatalogSync reads its index.json to discover community templates, rules, layouts, and plugins.

Community plugins must use the WASM runtime. Community templates, rules, and layouts have no runtime restriction. All community content is tagged with _source: "community" in the registry.

Community content is not covered by StudioBrain support. Review community templates before installing, especially if they include generation rules that will influence AI output.

Configuration

CatalogSync reads its configuration from environment variables:

Variable	Default	Description
`CATALOG_CACHE_DIR`	`~/.studiobrain/catalog`	Local directory for the cloned catalog repo
`CATALOG_REPO_URL`	`https://github.com/BiloxiStudios/studiobrain-templates.git`	Git URL of the official templates repo
`CATALOG_PLATFORM`	`core`	Edition filter: `core`, `desktop`, or `cloud`
`COMMUNITY_CACHE_DIR`	`~/.studiobrain/community-catalog`	Local directory for the community repo

Offline Behavior

If network access is unavailable, CatalogSync uses the previously cached content silently. Template discovery, entity creation, and all other features continue to work with the cached catalog. The background sync retries on the next interval.

Creating a Custom Override

To customize any template for your project:

Find the template you want to override in _Templates/Standard/ (or browse the marketplace).
Copy it to _Templates/Custom/ with the same filename.
Edit the frontmatter fields to match your needs.
Save. StudioBrain picks up the change immediately — no restart required.

# Example: customize the Character template
cp _Templates/Standard/CHARACTER_TEMPLATE.md _Templates/Custom/CHARACTER_TEMPLATE.md
# Edit _Templates/Custom/CHARACTER_TEMPLATE.md to add/remove fields

To revert to the Standard version, delete your Custom file.

Next Steps

Template System Overview — What templates are and how they work
AI Generation Rules — Constraints that guide AI content generation
Template Packs — Installing bundled template sets