Bundle Assets

Overview

Bundle Assets is a generic, capability-based mechanism that lets bundles carry their own files (skins, templates, embed snippets, locales) in a standard ./assets/ directory. Packs that need access to these files declare a capability, and the runtime grants read-only access at load time.

Consejo

This follows Maarten’s core design principle: generic mechanisms, not specific solutions. Rather than hard-coding paths like /template/demo/ for each use case, Greentic provides a single ./assets/ pattern that customers can extend in unforeseen ways. Specific paths create maintenance nightmares; a generic capability pattern scales.

How It Works

The bundle assets system has three moving parts:

1. Capability declaration — the bundle’s JSON AnswerDocument (or wizard prompts) declares which asset capabilities are enabled.
2. Scaffold — gtc wizard or gtc setup automatically copies eligible assets/webchat-gui/ files from extension .gtpack files into the bundle’s ./assets/ directory.
3. Overlay — at runtime, files in the bundle’s ./assets/ directory override matching files from the pack’s built-in defaults. This lets you customize skins, templates, and locale strings without modifying the pack itself.

Capabilities

Each capability unlocks a specific set of assets and behaviors. Capabilities follow the naming convention greentic.cap.{category}.v{N}.

Capability ID	Purpose	What It Enables
greentic.cap.bundle_assets.read.v1	Bundle-level asset directory	Creates the ./assets/ directory structure and scaffolds eligible default skin files from extension packs
greentic.cap.webchat.oauth.v1	OAuth authentication for WebChat	Adds OAuth auth provider configuration to tenant config files
greentic.cap.webchat.i18n.v1	Multi-language WebChat	Enables locale picker and scaffolds locale JSON files under ./assets/
greentic.cap.webchat.embed.v1	Embeddable WebChat widget	Generates embed HTML snippets (fullpage link, inline iframe, chat bubble) per tenant

Nota

Capabilities are additive. Enabling greentic.cap.webchat.embed.v1 implicitly requires greentic.cap.bundle_assets.read.v1 because the embed snippets are written to the ./assets/ directory.

Wizard Prompts

When you run gtc wizard, the wizard prompts for each capability:

? Enable bundle-level assets (./assets/)? [Y/n]
? Enable OAuth login for WebChat GUI? [y/N]
? Enable multi-language for WebChat GUI? [y/N]
? Enable embeddable WebChat widget? [y/N]

Answering “yes” to a capability adds it to the generated bundle and triggers the corresponding scaffold step.

You can also set capabilities directly in a JSON AnswerDocument without interactive prompts (see Configuration below).

Configuration

In the Wizard AnswerDocument

Start from the live schema instead of copying old examples:

gtc wizard --schema

gtc wizard --schema prints the current launcher schema, including the embedded greentic-bundle answer schema. Coding agents should fetch that schema first, fill a JSON AnswerDocument, validate it, then apply it.

bundle-assets-create-answers.json

{
  "wizard_id": "greentic-dev.wizard.launcher.main",
  "schema_id": "greentic-dev.launcher.main",
  "schema_version": "1.0.0",
  "locale": "en",
  "answers": {
    "selected_action": "bundle",
    "delegate_answer_document": {
      "wizard_id": "greentic-bundle.wizard.run",
      "schema_id": "greentic-bundle.wizard.answers",
      "schema_version": "1.0.0",
      "locale": "en",
      "answers": {
        "bundle_name": "My Digital Worker",
        "bundle_id": "my-digital-worker",
        "output_dir": "./my-digital-worker",
        "extension_providers": [
          "messaging-webchat"
        ],
        "capabilities": [
          "greentic.cap.bundle_assets.read.v1",
          "greentic.cap.webchat.oauth.v1",
          "greentic.cap.webchat.i18n.v1",
          "greentic.cap.webchat.embed.v1"
        ]
      },
      "locks": {
        "execution": "execute"
      }
    }
  },
  "locks": {
    "execution": "execute"
  }
}

gtc wizard validate --answers bundle-assets-create-answers.json
gtc wizard apply --answers bundle-assets-create-answers.json --yes

The answers file for gtc wizard is JSON only. The generated workspace still contains bundle.yaml; that file is runtime workspace state, not the wizard replay format.

In bundle.yaml

Capabilities are also recorded in the generated bundle.yaml so the runtime knows which features are active:

bundle.yaml

name: my-digital-worker
version: "1.0.0"

capabilities:
  - greentic.cap.bundle_assets.read.v1
  - greentic.cap.webchat.oauth.v1
  - greentic.cap.webchat.i18n.v1
  - greentic.cap.webchat.embed.v1

extension_providers:
  - "messaging-webchat"

How Scaffold Works

When a capability is enabled, the wizard (or setup) runs a scaffold step that populates the bundle’s ./assets/ directory with default files. The scaffold process:

1. Reads eligible files from extension packs

   Extension .gtpack files can ship files under assets/webchat-gui/, including skin JSON, HTML templates, CSS, locale JSON, and embed snippets. Bundle asset scaffold intentionally copies only this public webchat asset subtree; internal pack assets such as fixtures, schemas, and secret requirement files are not copied.

2. Copies public assets into the bundle

   The scaffold writes matching files to the same relative path under the bundle root, for example assets/webchat-gui/skins/demo/skin.json.

3. Preserves existing customizations

   Existing files are not overwritten. This is deliberate: once a team customizes ./assets/, setup and wizard reruns should not destroy those edits.

4. Generates embed snippets

   When greentic.cap.webchat.embed.v1 is enabled and the selected WebChat extension provides embed assets, those snippets are made available under assets/webchat-gui/embed/.

Directory Structure After Scaffold

With all four capabilities enabled and a single tenant demo, the bundle looks like this:

my-digital-worker/
├── bundle.yaml
├── providers/
│   └── messaging/
│       ├── messaging-webchat.gtpack
│       └── messaging-telegram.gtpack
├── assets/
│   └── webchat-gui/
│       ├── skins/
│       │   └── demo/                    # Per-tenant skin (copied from pack defaults)
│       │       ├── skin.json            # Theme colors, title, logo, feature flags
│       │       ├── fullpage/
│       │       │   ├── index.html       # Fullpage chat HTML
│       │       │   └── page.css         # Fullpage custom CSS
│       │       ├── embed/
│       │       │   └── bubble.css       # Chat bubble custom CSS
│       │       └── i18n/
│       │           ├── en.json          # English locale strings
│       │           └── id.json          # Indonesian locale strings
│       └── embed/
│           └── demo.html               # Generated embed snippets for tenant
├── tenants/
│   └── demo/
│       ├── tenant.gmap
│       └── teams/
│           └── default/
│               └── team.gmap
└── seeds.yaml

Overlay Mechanism

At runtime, the Greentic platform resolves asset files using an overlay strategy:

1. Bundle files take priority. If a file exists in ./assets/webchat-gui/skins/{tenant}/skin.json, it is used instead of the pack’s built-in skins/default/skin.json.
2. Pack defaults are the fallback. If the bundle does not override a file, the pack’s built-in version is used.
3. Overlay is per-file. You can override skin.json while keeping the pack’s default page.css. There is no all-or-nothing requirement.

This means you can safely edit files in ./assets/ to customize your deployment without forking or rebuilding the pack.

Precaución

When you upgrade an extension pack to a new version, review your overridden files. New pack versions may add fields to skin.json or change the HTML template structure. Your bundle overlay will still take priority, so you need to merge any new changes manually.

Example: Customizing the WebChat Skin

After scaffold, edit the skin configuration to match your brand:

assets/webchat-gui/skins/demo/skin.json

{
  "title": "Acme Support",
  "subtitle": "We are here to help",
  "logo": "/assets/webchat-gui/skins/demo/logo.png",
  "primaryColor": "#E63946",
  "backgroundColor": "#F1FAEE",
  "showLocalePicker": true,
  "showOAuthLogin": true,
  "embedEnabled": true
}

The runtime serves this skin when a user connects to the WebChat for the demo tenant. No pack rebuild is needed.

Next Steps

• WebChat Embedding — embed types and configuration reference
• WebChat Extension — full WebChat setup and features
• Packs — how packs declare and consume capabilities
• gtc wizard — wizard answers file reference