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)

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:

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

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.

Three-Way Merge (Cloud)

StudioBrain Cloud only. The three-way merge system is part of the DB-backed template overlay layer and does not exist in core.

When you accept a template version update and have a Custom override, the overlay system performs a three-way merge to reconcile your customizations with the updated Standard template:

  base (original fork-point — Standard version when you customized)
  new_base (updated Standard template from catalog)
  user_overlay (your Custom/ overrides)
  ──────────────────────────────────────────────────────────
  merged (result — your changes preserved, new fields added)

How It Works

The merge runs per-field and follows these rules:

Conflicts are never blocking — your customizations are always preserved. Conflicting fields are logged for audit purposes and recorded in pending_conflicts so you can review them later if needed.

Dry-Run Preview

Before accepting a merge, you can preview what will change:

GET /api/templates/updates/:entity_type

This returns a diff showing which fields will be added, removed, or conflicted. To see the full conflict details:

GET /api/templates/updates/:entity_type/conflicts

Resolving Conflicts

If you want to accept a Standard template’s value for a specific conflicted field:

POST /api/templates/updates/:entity_type/resolve
{
  "field_name": "some_field",
  "resolution": "use_base" | "use_user"
}

To trigger the full three-way merge and persist the result:

POST /api/templates/updates/:entity_type/merge
{
  "new_base": { /* fields from updateded Standard template */ },
  "base": { /* optional: original fork-point, defaults to current merged */ }
}

The merge response includes a full MergeReport with added, removed, conflicts, and per-field field_diffs so you can inspect what happened.

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)

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

1. On startup, CatalogSync clones (or pulls) the studiobrain-templates repo into ~/.studiobrain/catalog/.
2. 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.
3. A background task refreshes the catalog every 1 hour (configurable via the start_periodic_sync interval).
4. New or updated templates, rules, skills, and layouts are upserted into the marketplace registry database.

What Gets Synced

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.

Configuration

CatalogSync reads its configuration from environment variables:

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:

1. Find the template you want to override in _Templates/Standard/ (or browse the marketplace).
2. Copy it to _Templates/Custom/ with the same filename.
3. Edit the frontmatter fields to match your needs.
4. 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