Template Packs System

Template Packs are versioned bundles of entity templates, AI generation rules, and example entities. They are the distribution unit for sharing reusable entity type definitions — both within a team and on the public StudioBrain Marketplace.

What Are Template Packs?

A Template Pack is a directory containing:

my-pack/
  pack.json          # Pack metadata (required)
  templates/         # Template files for each entity type
    CHARACTER_TEMPLATE.md
    LOCATION_TEMPLATE.md
  examples/          # Sample entity markdown files
    example_character.md
  rules/             # AI generation rules for these types
    character_style.yaml
  README.md          # Human-readable documentation (recommended)
  icon.png           # 128x128 icon for the Marketplace card (optional)

Packs are discovered from _Templates/Packs/ at startup. The TemplatePacks service scans this directory recursively and registers each valid pack.

Pack Structure

pack.json

The pack.json file is required and must be valid JSON:

{
  "id": "game-dev-essentials",
  "name": "Game Dev Essentials",
  "description": "Core entity types for game projects: factions, creatures, quests, and items.",
  "author": "Biloxi Studios",
  "version": "1.2.0",
  "entity_types": ["faction", "creature", "item"],
  "categories": ["entity"],
  "tags": ["game", "rpg", "narrative"],
  "icon": "icon.png",
  "includes": []
}

Fields:

Template Files

Template files in templates/ follow the standard YAML frontmatter format. The filename must match the pattern {UPPERCASE_TYPE}_TEMPLATE.md. The entity type slug in the entity_type frontmatter field must match the lowercase filename stem:

templates/FACTION_TEMPLATE.md  →  entity_type: "faction"
templates/CREATURE_TEMPLATE.md →  entity_type: "creature"

Example Files

Example files in examples/ are valid entity markdown files that demonstrate the template in use. They are used during pack testing and shown in the Marketplace preview:

---
entity_type: faction
id: "iron_fist_guild"
name: "Iron Fist Guild"
faction_type: "mercenary"
alignment: "neutral"
size: "medium"
...
---
 
## Overview
 
The Iron Fist Guild is a mercenary organization operating out of Port Arkon...

Rule Files

Rule files in rules/ are AI generation rule YAML files that are imported when the pack is installed. Rules are scoped to the pack’s entity types and appear in Settings > Rules alongside the built-in rules.

Pack Development

Creating a Pack

1. Create a directory in _Templates/Packs/:

   mkdir -p _Templates/Packs/my-pack/templates
   mkdir -p _Templates/Packs/my-pack/examples
   mkdir -p _Templates/Packs/my-pack/rules

2. Create pack.json with your pack metadata.

3. Add template files to templates/. Use _Templates/Standard/CHARACTER_TEMPLATE.md as a reference for the expected frontmatter fields.

4. Add at least one example entity to examples/.

5. Restart the backend to pick up the new pack:

   # LXC 138 (Docker deployment)
   ssh root@10.15.0.30 "pct exec 138 -- bash -c 'cd /opt/studiobrain/app/docker && docker compose restart backend'"

6. Verify the pack loads: check the backend logs for Discovered pack: my-pack and confirm the pack appears in Settings > Templates.

Pack Metadata

The TemplatePack dataclass (defined in services/template_packs.py) holds the parsed pack state:

@dataclass
class TemplatePack:
    id: str
    name: str
    description: str
    author: str
    version: str
    entity_types: List[str]
    categories: List[str]
    tags: List[str]
    icon: Optional[str]
    pack_dir: Optional[Path]
    template_files: Dict[str, Path]   # entity_type -> template path
    example_files: List[Path]
    rule_files: List[Path]
    is_meta_pack: bool
    includes: List[str]               # pack IDs included in a meta-pack

Meta-Packs

A meta-pack does not define its own templates — it is a named bundle of other packs. Setting is_meta_pack: true in pack.json and listing pack IDs in includes causes the service to treat this as a shortcut installer:

{
  "id": "game-studio-bundle",
  "name": "Game Studio Bundle",
  "description": "All game development packs in one install",
  "author": "Biloxi Studios",
  "version": "1.0.0",
  "entity_types": [],
  "includes": ["game-dev-essentials", "narrative-packs", "world-building"]
}

Installing a meta-pack installs all included packs and activates their entity types (subject to plan limits).

Dependencies

Packs may declare dependencies on other packs in pack.json via the dependencies field (planned feature). The installer will prompt to install required packs before the dependent pack. Until this is implemented, declare dependencies in README.md.

Pack Distribution

Marketplace Submission

When the StudioBrain Marketplace launches, pack submission will be handled via the API:

POST /api/marketplace/packs
Content-Type: multipart/form-data
 
pack_dir=<zip archive>
pack_json=<pack.json contents>

The submission process will:

1. Validate pack.json completeness
2. Validate all template files parse without errors
3. Check for namespace conflicts with existing marketplace packs
4. Submit for review (community review queue for free tier; expedited for Team/Enterprise)

Version Management

Follow semantic versioning when releasing pack updates:

• Patch (1.0.0 → 1.0.1): Fix typos, correct field defaults, adjust rule weights
• Minor (1.0.0 → 1.1.0): Add new fields (backward compatible), add new rule files, add example entities
• Major (1.0.0 → 2.0.0): Rename or remove fields, change entity type slugs, restructure frontmatter hierarchy

For major version updates, include a MIGRATION.md in the pack root describing the changes and how to update existing entities.

Update Distribution

StudioBrain checks for pack updates from the marketplace on a configurable interval (default: once per day). When an update is available:

• For patch updates: offer one-click auto-update with a changelog summary
• For minor updates: show the new fields added and confirm before applying
• For major updates: open the migration wizard before applying

Installed packs are tracked in the database (PackInstallation model) with the current version and installation date. The TemplatePacks service compares installed versions against the marketplace registry to determine available updates.

Local Distribution

For team-internal packs that should not be published to the public marketplace:

1. Git repository: include _Templates/Packs/ in your project’s git repository. All team members get the pack via git pull.
2. Shared network drive: place the pack directory on the NAS under the project content directory. All StudioBrain instances that mount the NAS will discover the pack automatically.
3. Private marketplace (Enterprise): Enterprise plans can host a private marketplace registry for organization-internal packs.

API Reference

The Template Packs API exposes pack discovery and install operations:

See REST API Reference for full endpoint documentation and authentication details.

See Also

• Template Categories Architecture — Category classification and multi-directory discovery
• Template Authoring — Writing YAML frontmatter and field definitions
• Template Marketplace — End-user guide for finding and installing packs
• Template Categories User Guide — Activating entity types per-project