bananahub 0.1.2 → 0.1.3

package/README.md

@@ -1,9 +1,17 @@
 # bananahub
 
-Template manager for [BananaHub Skill](https://github.com/bananahub-ai/bananahub-skill) — the agent-native Gemini image workflow.
+Template manager for [BananaHub Skill](https://github.com/bananahub-ai/bananahub-skill) — the agent-native multi-provider image workflow.
 
 Install, manage, and share prompt or workflow modules for the BananaHub Skill workflow. BananaHub keeps the runtime lean and lets reusable prompt structures and guided SOPs travel as installable units.
 
+## Model Strategy
+
+BananaHub now treats provider/model choice as a first-class interaction:
+
+- Prefer `gpt-image-2` for new high-quality generation, launch visuals, README covers, information graphics, and premium first-pass outputs.
+- Prefer Gemini / Nano Banana (`gemini-3-pro-image-preview` first) for edit-heavy, multi-reference, consistency-heavy, and previously validated template workflows.
+- Templates can declare provider/model support explicitly, so `bananahub` can surface the recommended model instead of treating all image models as interchangeable.
+
 ## Installation
 
 ```bash
@@ -27,8 +35,8 @@ npx bananahub <command>
 Install template(s) from a GitHub repository, a specific template directory, or a known template collection.
 
 ```bash
-bananahub add user/bananahub-cyberpunk
-bananahub add bananahub-ai/bananahub-skill/cute-sticker
+bananahub add user/bananahub-infographics
+bananahub add bananahub-ai/templates/cute-sticker
 bananahub add user/multi-template-repo --template portrait
 ```
 
@@ -44,12 +52,13 @@ Uninstall an installed template.
 bananahub remove cyberpunk
 ```
 
-### `list`
+### `list [--by-model]`
 
 List all installed templates.
 
 ```bash
 bananahub list
+bananahub list --by-model
 ```
 
 ### `update [template-id]`
@@ -69,6 +78,18 @@ Show details about an installed template (metadata, version, source).
 bananahub info cyberpunk
 ```
 
+`info` now shows provider/model support and suggests an explicit override when a template has a stronger recommended model, for example `gpt-image-2`.
+
+### `models [--remote]`
+
+Show BananaHub's model support map from the local registry or the remote hub catalog.
+
+```bash
+bananahub models
+bananahub models --remote
+bananahub models --provider openai
+```
+
 ### `search <keyword>`
 
 Search the hub catalog for prompt or workflow templates.
@@ -76,12 +97,17 @@ Search the hub catalog for prompt or workflow templates.
 ```bash
 bananahub search portrait
 bananahub search logo --curated
+bananahub search logo --model gpt-image-2
+bananahub search diagram --provider openai --capability generation
 ```
 
 Options:
 - `--limit <n>` — Limit the number of results (default: 8, max: 20)
 - `--curated` — Search only curated templates
 - `--discovered` — Search only discovered templates
+- `--provider <id>` — Filter by provider, for example `openai` or `google-ai-studio`
+- `--model <id>` — Filter by canonical model id or alias, for example `gpt-image-2` or `nano-banana-pro`
+- `--capability <name>` — Filter by capability such as `generation`, `edit`, or `mask_edit`
 
 ### `trending`
 

package/bin/bananahub.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
 import { bold, dim, cyan, yellow } from '../lib/color.js';
+import { CLI_VERSION } from '../lib/version.js';
 
-const VERSION = '0.1.1';
+const VERSION = CLI_VERSION;
 
 const HELP = `
 ${bold('bananahub')} ${dim(`v${VERSION}`)} — Template manager for BananaHub Skill
@@ -15,10 +16,11 @@ ${bold('COMMANDS')}
       --template <name>               Pick one template from a multi-template directory
       --all                           Install all templates from a collection
   ${cyan('remove')} <template-id>                Uninstall a template
-  ${cyan('list')}                                List installed templates
+  ${cyan('list')} [--by-model]                   List installed templates
   ${cyan('update')} [template-id]                Update one or all installed templates
   ${cyan('info')} <template-id>                  Show template details
-  ${cyan('search')} <keyword> [--limit N] [--curated|--discovered]
+  ${cyan('models')} [--remote] [--provider P]    Show provider/model support map
+  ${cyan('search')} <keyword> [--limit N] [--provider P] [--model M]
                                        Search hub for templates
   ${cyan('trending')} [--period 24h|7d] [--limit N]
                                        Show trending templates
@@ -31,12 +33,14 @@ ${bold('OPTIONS')}
   --version, -v             Show version
 
 ${bold('EXAMPLES')}
-  bananahub add user/bananahub-cyberpunk
-  bananahub add bananahub-ai/bananahub-skill/cute-sticker
+  bananahub add user/bananahub-infographics
+  bananahub add bananahub-ai/templates/cute-sticker
   bananahub add user/multi-template-repo --template portrait
   bananahub search logo --curated
+  bananahub search logo --model gpt-image-2
+  bananahub models --remote
   bananahub trending --period 7d
-  bananahub list
+  bananahub list --by-model
   bananahub validate ./my-template
   bananahub init
   bananahub init --type workflow
@@ -70,7 +74,7 @@ async function main() {
     }
     case 'list': {
       const { listCommand } = await import('../lib/commands/list.js');
-      await listCommand();
+      await listCommand(cmdArgs);
       break;
     }
     case 'update': {
@@ -83,6 +87,11 @@ async function main() {
       await infoCommand(cmdArgs);
       break;
     }
+    case 'models': {
+      const { modelsCommand } = await import('../lib/commands/models.js');
+      await modelsCommand(cmdArgs);
+      break;
+    }
     case 'search': {
       const { searchCommand } = await import('../lib/commands/search.js');
       await searchCommand(cmdArgs);

package/lib/commands/add.js

@@ -8,7 +8,8 @@ import { extract } from 'tar';
 import { downloadTarball, getDefaultBranchInfo, getLatestSha } from '../github.js';
 import { validateTemplate } from '../validate.js';
 import { rebuildRegistry } from '../registry.js';
-import { TEMPLATES_DIR, CLI_VERSION, HUB_API, SKILL_COMMAND } from '../constants.js';
+import { TEMPLATES_DIR, HUB_API, SKILL_COMMAND } from '../constants.js';
+import { CLI_VERSION } from '../version.js';
 import { bold, green, red, yellow, cyan, dim } from '../color.js';
 
 const KNOWN_TEMPLATE_ROOTS = ['references/templates', 'templates'];

package/lib/commands/info.js

@@ -5,6 +5,7 @@ import { parseFrontmatter } from '../frontmatter.js';
 import { bold, dim, cyan, green } from '../color.js';
 import { red } from '../color.js';
 import { resolveInstalledTemplateDir } from '../paths.js';
+import { MODEL_DISPLAY, normalizeProviders } from '../template-schema.js';
 
 export async function infoCommand(args) {
   const id = args[0];
@@ -58,7 +59,7 @@ export async function infoCommand(args) {
   }
 
   if (fm.models?.length) {
-    console.log(`  ${cyan('Models'.padEnd(12))}`);
+    console.log(`  ${cyan('Legacy'.padEnd(12))}`);
     for (const m of fm.models) {
       const name = m.name || m;
       const quality = m.quality ? ` (${m.quality})` : '';
@@ -66,6 +67,28 @@ export async function infoCommand(args) {
     }
   }
 
+  const providers = normalizeProviders(fm);
+  if (providers.length) {
+    console.log(`  ${cyan('Providers'.padEnd(12))}`);
+    for (const provider of providers) {
+      const family = provider.family ? dim(` [${provider.family}]`) : '';
+      console.log(`    - ${provider.id}${family}`);
+      for (const model of provider.models) {
+        const quality = model.quality ? dim(` (${model.quality})`) : '';
+        const variant = model.prompt_variant ? dim(` via ${model.prompt_variant}`) : '';
+        const recommendation = MODEL_DISPLAY[model.id]?.tier === 'recommended' ? dim(' recommended') : '';
+        console.log(`      - ${model.id}${quality}${variant}${recommendation}`);
+      }
+    }
+  }
+
+  if (fm.capabilities && typeof fm.capabilities === 'object') {
+    const capabilities = Object.entries(fm.capabilities)
+      .map(([key, value]) => `${key}=${value}`)
+      .join(', ');
+    console.log(`  ${cyan('Capabilities'.padEnd(12))} ${capabilities}`);
+  }
+
   if (source) {
     console.log();
     console.log(dim(`  Source: ${source.repo}`));
@@ -73,5 +96,22 @@ export async function infoCommand(args) {
     if (source.sha) console.log(dim(`  SHA: ${source.sha.slice(0, 8)}`));
   }
 
-  console.log(green(`\n  Use: ${SKILL_COMMAND} use ${id}\n`));
+  console.log(green(`\n  Use: ${SKILL_COMMAND} use ${id}`));
+  const recommended = findRecommendedProviderModel(providers);
+  if (recommended) {
+    console.log(dim(`  Provider override: ${SKILL_COMMAND} use ${id} --provider ${recommended.provider} --model ${recommended.model}`));
+  }
+  console.log();
+}
+
+function findRecommendedProviderModel(providers) {
+  for (const provider of providers) {
+    const model = provider.models.find((entry) => entry.id === 'gpt-image-2');
+    if (model) return { provider: provider.id, model: model.id };
+  }
+  for (const provider of providers) {
+    const model = provider.models.find((entry) => entry.quality === 'best') || provider.models[0];
+    if (model) return { provider: provider.id, model: model.id };
+  }
+  return null;
 }

package/lib/commands/init.js

@@ -106,7 +106,19 @@ Reusable prompt block or instruction fragment for this workflow
   return `## Prompt Template
 
 \`\`\`
-Your prompt here with {{variable|default value}} slots
+Provider-neutral base prompt with {{variable|default value}} slots. Keep this conservative and avoid model-specific hacks.
+\`\`\`
+
+## Prompt Template: gemini
+
+\`\`\`
+Gemini/Nano Banana tuned prompt with {{variable|default value}} slots. Use descriptive scene language, preserve exact quoted labels when needed, and avoid generic quality tags.
+\`\`\`
+
+## Prompt Template: gpt-image
+
+\`\`\`
+GPT Image tuned prompt with {{variable|default value}} slots. State exact constraints, what to avoid, and any text/label limits explicitly.
 \`\`\`
 
 ## Variables
@@ -117,7 +129,8 @@ Your prompt here with {{variable|default value}} slots
 
 ## Tips
 
-- Add tips for using this template
+- Keep provider-specific tactics inside the matching prompt variant
+- Do not reuse a Gemini-tuned prompt for GPT Image unless it has been tested and documented
 `;
 }
 
@@ -134,19 +147,20 @@ npx bananahub add your-username/${id}
 
 ## Verified Models
 
-- \`gemini-3-pro-image-preview\` — validate the primary flow with a real sample before publishing
+- \`gemini-3-pro-image-preview\` via \`gemini\` prompt variant — validate with a real sample before publishing
 
 ## Supported Models
 
-- \`gemini-3.1-flash-image-preview\` — expected to work, not yet manually verified
+- \`gemini-3.1-flash-image-preview\` via \`gemini\` prompt variant — expected to work, not yet manually verified
+- \`gpt-image-2\` via \`gpt-image\` prompt variant — only list as verified after generating a real sample
 
 ## Sample Outputs
 
-| File | Model | Prompt / Variant |
-|---|---|---|
-| \`samples/sample-3-pro-01.png\` | \`gemini-3-pro-image-preview\` | Replace with your real sample or representative workflow output |
+| File | Provider | Model | Prompt Variant |
+|---|---|---|---|
+| \`samples/sample-3-pro-01.png\` | \`google-ai-studio\` | \`gemini-3-pro-image-preview\` | \`gemini\` |
 
-Update this README after you generate real samples. Each sample filename should include the generating model shorthand, for example \`sample-3-pro-01.png\` or \`sample-3.1-flash-01.png\`.
+Update this README after you generate real samples. Each sample should name the provider, exact model, and prompt variant used.
 
 ## License
 
@@ -186,7 +200,9 @@ export async function initCommand(args) {
 
   const sampleFrontmatter = type === 'prompt' ? `samples:
   - file: samples/sample-3-pro-01.png
+    provider: google-ai-studio
     model: gemini-3-pro-image-preview
+    prompt_variant: gemini
     prompt: "The exact prompt used to generate this sample"
     aspect: "16:9"` : `samples: []`;
 
@@ -207,6 +223,32 @@ models:
   - name: gemini-3.1-flash-image-preview
     tested: false
     quality: good
+providers:
+  - id: google-ai-studio
+    family: gemini-image
+    models:
+      - id: gemini-3-pro-image-preview
+        aliases: [nano-banana-pro]
+        quality: best
+        prompt_variant: gemini
+      - id: gemini-3.1-flash-image-preview
+        aliases: [nano-banana-2]
+        quality: good
+        prompt_variant: gemini
+  - id: openai
+    family: gpt-image
+    models:
+      - id: gpt-image-2
+        quality: untested
+        prompt_variant: gpt-image
+capabilities:
+  generation: true
+  edit: false
+  mask_edit: false
+prompt_variants:
+  default: base
+  gemini: prompt-gemini
+  gpt-image: prompt-gpt-image
 aspect: "16:9"
 difficulty: ${difficulty}
 ${sampleFrontmatter}

package/lib/commands/list.js

@@ -1,7 +1,8 @@
 import { loadRegistry } from '../registry.js';
 import { bold, dim, cyan, yellow } from '../color.js';
+import { collectModelSupport } from '../template-schema.js';
 
-export async function listCommand() {
+export async function listCommand(args = []) {
   const registry = await loadRegistry();
   const templates = registry.templates || [];
 
@@ -11,6 +12,11 @@ export async function listCommand() {
     return;
   }
 
+  if (args.includes('--by-model') || args.includes('--by-provider')) {
+    printByModel(templates);
+    return;
+  }
+
   // Group by profile
   const groups = {};
   for (const t of templates) {
@@ -32,6 +38,27 @@ export async function listCommand() {
       if (t.tags?.length) {
         console.log(dim(`      Tags: ${t.tags.join(', ')}`));
       }
+      if (t.providers?.length || t.models?.length) {
+        const providers = t.providers?.length ? t.providers.join(', ') : 'providers n/a';
+        const models = t.models?.length ? t.models.slice(0, 4).join(', ') : 'models n/a';
+        console.log(dim(`      Support: ${providers} | ${models}`));
+      }
+    }
+    console.log();
+  }
+}
+
+function printByModel(templates) {
+  const models = collectModelSupport(templates);
+  console.log(bold(`\n  Installed Templates by Model (${templates.length})\n`));
+
+  for (const model of models.sort((left, right) => right.template_count - left.template_count || left.id.localeCompare(right.id))) {
+    console.log(cyan(`  ${model.id}`) + dim(`  ${model.provider || 'provider n/a'}${model.family ? `/${model.family}` : ''}`));
+    for (const templateId of model.templates.slice(0, 12)) {
+      console.log(`    - ${templateId}`);
+    }
+    if (model.templates.length > 12) {
+      console.log(dim(`    ... ${model.templates.length - 12} more`));
     }
     console.log();
   }

package/lib/commands/models.js

@@ -0,0 +1,129 @@
+import { bold, cyan, dim, green, red, yellow } from '../color.js';
+import { fetchHubCatalog } from '../hub.js';
+import { loadRegistry } from '../registry.js';
+import {
+  MODEL_DISPLAY,
+  collectModelSupport,
+  templateSupportsProviderModel
+} from '../template-schema.js';
+
+export async function modelsCommand(args = []) {
+  const options = parseModelsArgs(args);
+  let templates;
+  let sourceLabel;
+
+  try {
+    if (options.remote) {
+      const catalog = await fetchHubCatalog();
+      templates = catalog.templates || [];
+      sourceLabel = 'hub catalog';
+    } else {
+      const registry = await loadRegistry();
+      templates = registry.templates || [];
+      sourceLabel = 'local registry';
+    }
+  } catch (error) {
+    console.error(red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+
+  const filteredTemplates = templates.filter((template) => templateSupportsProviderModel(template, options));
+  const models = collectModelSupport(filteredTemplates)
+    .filter((model) => !options.provider || model.provider === options.provider)
+    .sort(compareModels);
+
+  console.log(bold(`\n  BananaHub Model Map (${sourceLabel})\n`));
+  console.log(dim('  Use this to choose a provider/model before installing or activating templates.'));
+  console.log(dim('  Recommendation: use gpt-image-2 for new high-quality generation when OpenAI is available; use Gemini/Nano Banana for proven template/edit workflows.\n'));
+
+  if (models.length === 0) {
+    console.log(yellow('  No models matched the current filters.\n'));
+    return;
+  }
+
+  for (const model of models) {
+    printModel(model, options);
+  }
+
+  console.log(green('  Examples:'));
+  console.log(dim('    bananahub search logo --model gpt-image-2'));
+  console.log(dim('    bananahub search diagram --provider openai --capability generation'));
+  console.log(dim('    bananahub list --by-model\n'));
+}
+
+function parseModelsArgs(args) {
+  const options = {
+    remote: false,
+    provider: '',
+    model: '',
+    capability: ''
+  };
+
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--remote' || arg === '--hub') {
+      options.remote = true;
+      continue;
+    }
+    if (arg === '--provider') {
+      options.provider = args[index + 1] || '';
+      index++;
+      continue;
+    }
+    if (arg === '--model') {
+      options.model = args[index + 1] || '';
+      index++;
+      continue;
+    }
+    if (arg === '--capability') {
+      options.capability = args[index + 1] || '';
+      index++;
+      continue;
+    }
+  }
+
+  return options;
+}
+
+function compareModels(left, right) {
+  const rankDiff = modelRank(left.id) - modelRank(right.id);
+  if (rankDiff !== 0) return rankDiff;
+  const countDiff = right.template_count - left.template_count;
+  if (countDiff !== 0) return countDiff;
+  return left.id.localeCompare(right.id);
+}
+
+function modelRank(modelId) {
+  if (modelId === 'gpt-image-2') return 0;
+  if (modelId === 'gemini-3-pro-image-preview') return 1;
+  if (modelId === 'gemini-3.1-flash-image-preview') return 2;
+  if (modelId.startsWith('gpt-image')) return 3;
+  if (modelId.startsWith('gemini')) return 4;
+  return 9;
+}
+
+function printModel(model, options) {
+  const display = MODEL_DISPLAY[model.id] || {};
+  const label = display.label || model.id;
+  const tier = display.tier ? dim(` ${display.tier}`) : '';
+  const provider = model.provider ? dim(` ${model.provider}`) : '';
+  const family = model.family ? dim(`/${model.family}`) : '';
+  const templates = model.templates.slice(0, 5).join(', ');
+
+  console.log(`  ${bold(model.id)}${tier}`);
+  console.log(`    ${cyan(label)}${provider}${family}`);
+  if (display.note) {
+    console.log(dim(`    ${display.note}`));
+  }
+  if (model.aliases.length) {
+    console.log(dim(`    Aliases: ${model.aliases.join(', ')}`));
+  }
+  if (model.capabilities.length) {
+    console.log(dim(`    Capabilities: ${model.capabilities.join(', ')}`));
+  }
+  console.log(dim(`    Templates: ${model.template_count}${templates ? ` (${templates}${model.templates.length > 5 ? ', ...' : ''})` : ''}`));
+  if (options.model && model.id !== options.model) {
+    console.log(dim(`    Matched by alias/filter: ${options.model}`));
+  }
+  console.log();
+}

package/lib/commands/search.js

@@ -1,13 +1,14 @@
 import { bold, cyan, dim, green, red, yellow } from '../color.js';
 import { fetchHubCatalog, fetchHubTrending, buildCatalogLookup, compareCatalogPriority, templateKey } from '../hub.js';
 import { HUB_SITE } from '../constants.js';
+import { canonicalizeModelId, templateSupportsProviderModel } from '../template-schema.js';
 
 export async function searchCommand(args) {
   const options = parseSearchArgs(args);
   const keyword = options.terms.join(' ').trim();
 
   if (!keyword) {
-    console.error(red('Usage: bananahub search <keyword> [--limit N] [--curated|--discovered]'));
+    console.error(red('Usage: bananahub search <keyword> [--limit N] [--curated|--discovered] [--provider P] [--model M] [--capability C]'));
     process.exit(1);
   }
 
@@ -81,7 +82,10 @@ function parseSearchArgs(args) {
   const options = {
     terms: [],
     limit: 8,
-    source: 'all'
+    source: 'all',
+    provider: '',
+    model: '',
+    capability: ''
   };
 
   for (let index = 0; index < args.length; index++) {
@@ -99,6 +103,21 @@ function parseSearchArgs(args) {
       options.source = 'discovered';
       continue;
     }
+    if (arg === '--provider') {
+      options.provider = args[index + 1] || '';
+      index++;
+      continue;
+    }
+    if (arg === '--model') {
+      options.model = canonicalizeModelId(args[index + 1] || '');
+      index++;
+      continue;
+    }
+    if (arg === '--capability') {
+      options.capability = args[index + 1] || '';
+      index++;
+      continue;
+    }
     options.terms.push(arg);
   }
 
@@ -133,6 +152,7 @@ function rankTemplates(templates, keyword, options) {
 
   return templates
     .filter((template) => options.source === 'all' || template.catalog_source === options.source)
+    .filter((template) => templateSupportsProviderModel(template, options))
     .map((template) => ({
       template,
       score: scoreTemplate(template, query, terms)
@@ -155,17 +175,26 @@ function scoreTemplate(template, query, terms) {
   const description = normalize(template.description);
   const profile = normalize(template.profile);
   const tags = (template.tags || []).map((tag) => normalize(tag));
+  const providers = (template.providers || []).map((provider) => normalize(provider));
+  const models = (template.models || []).map((model) => normalize(model));
+  const capabilities = Object.entries(template.capabilities || {})
+    .filter(([, value]) => value === true || value === 'true')
+    .map(([key]) => normalize(key));
 
   let relevance = 0;
 
   if (id === query) relevance += 100;
   if (title === query || titleEn === query) relevance += 80;
   if (tags.includes(query)) relevance += 60;
+  if (providers.includes(query) || models.includes(query)) relevance += 50;
+  if (capabilities.includes(query)) relevance += 20;
 
   if (id.includes(query)) relevance += 24;
   if (title.includes(query) || titleEn.includes(query)) relevance += 24;
   if (description.includes(query)) relevance += 12;
   if (profile.includes(query)) relevance += 8;
+  if (providers.some((provider) => provider.includes(query))) relevance += 12;
+  if (models.some((model) => model.includes(query))) relevance += 12;
 
   for (const term of terms) {
     if (term === query) continue;
@@ -175,6 +204,9 @@ function scoreTemplate(template, query, terms) {
     if (title.includes(term) || titleEn.includes(term)) relevance += 5;
     if (description.includes(term)) relevance += 2;
     if (profile.includes(term)) relevance += 2;
+    if (providers.some((provider) => provider.includes(term))) relevance += 4;
+    if (models.some((model) => model.includes(term))) relevance += 4;
+    if (capabilities.includes(term)) relevance += 3;
   }
 
   if (relevance === 0) {
@@ -208,6 +240,42 @@ function normalize(value) {
   return String(value || '').trim().toLowerCase();
 }
 
+function formatProviderIds(template) {
+  const ids = [];
+  for (const provider of template.providers || []) {
+    if (typeof provider === 'string') {
+      ids.push(provider);
+    } else if (provider?.id) {
+      ids.push(provider.id);
+    }
+  }
+  return [...new Set(ids.filter(Boolean))];
+}
+
+function formatModelIds(template) {
+  const ids = [];
+  for (const model of template.models || []) {
+    if (typeof model === 'string') {
+      ids.push(model);
+    } else if (model?.id || model?.name) {
+      ids.push(model.id || model.name);
+    }
+  }
+  for (const provider of template.providers || []) {
+    if (!provider || typeof provider === 'string') {
+      continue;
+    }
+    for (const model of provider.models || []) {
+      if (typeof model === 'string') {
+        ids.push(model);
+      } else if (model?.id || model?.name) {
+        ids.push(model.id || model.name);
+      }
+    }
+  }
+  return [...new Set(ids.filter(Boolean))];
+}
+
 function printTemplateResult(index, template) {
   const title = template.title_en || template.title || template.id;
   const subtitle = template.title && template.title_en ? template.title : '';
@@ -226,6 +294,11 @@ function printTemplateResult(index, template) {
   if (template.tags?.length) {
     console.log(dim(`      Tags: ${template.tags.slice(0, 6).join(', ')}`));
   }
+  if (template.providers?.length || template.models?.length) {
+    const providers = formatProviderIds(template).slice(0, 3).join(', ');
+    const models = formatModelIds(template).slice(0, 4).join(', ');
+    console.log(dim(`      Support: ${providers || 'providers n/a'}${models ? ` | ${models}` : ''}`));
+  }
   if (primaryCmd) {
     console.log(dim(`      ${commandLabel}: ${primaryCmd}`));
   }

package/lib/constants.js

@@ -1,7 +1,6 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-export const CLI_VERSION = '0.1.1';
 export const CONFIG_HOME = join(homedir(), '.config', 'bananahub');
 export const TEMPLATES_DIR = join(CONFIG_HOME, 'templates');
 export const REGISTRY_FILE = '.registry.json';

package/lib/frontmatter.js

@@ -1,6 +1,7 @@
 /**
  * Minimal YAML frontmatter parser.
- * Handles the subset used by template.md files (scalars, arrays, objects-in-arrays).
+ * Handles the subset used by template.md files (scalars, arrays, objects-in-arrays,
+ * and one nested object-array level for providers[].models[]).
  */
 
 export function parseFrontmatter(text) {
@@ -47,25 +48,52 @@ function parseYaml(text) {
 
     // Empty value — check for block array/object below
     if (value === '') {
-      // Look ahead for block array (lines starting with "  - ")
       const items = [];
       let j = i + 1;
       while (j < lines.length && lines[j].match(/^  - /)) {
         const itemLine = lines[j].replace(/^  - /, '').trim();
-        // Check if this array item has sub-keys
         let k = j + 1;
         const subKeys = {};
         let hasSubKeys = false;
-        while (k < lines.length && lines[k].match(/^    \w/)) {
+        while (k < lines.length && lines[k].match(/^    /)) {
+          if (lines[k].match(/^      /)) {
+            k++;
+            continue;
+          }
           const subMatch = lines[k].match(/^    (\w[\w_]*):\s*(.*)/);
           if (subMatch) {
             hasSubKeys = true;
+            const nestedKey = subMatch[1];
             let sv = subMatch[2].trim();
-            if ((sv.startsWith('"') && sv.endsWith('"')) ||
-                (sv.startsWith("'") && sv.endsWith("'"))) {
-              sv = sv.slice(1, -1);
+
+            if (sv === '') {
+              const nestedItems = [];
+              k++;
+              while (k < lines.length && lines[k].match(/^      - /)) {
+                const nestedItemLine = lines[k].replace(/^      - /, '').trim();
+                const nestedObj = {};
+                const nestedFirstKey = nestedItemLine.match(/^(\w[\w_]*):\s*(.*)/);
+                if (nestedFirstKey) {
+                  nestedObj[nestedFirstKey[1]] = coerceValue(nestedFirstKey[2].trim());
+                  k++;
+                  while (k < lines.length && lines[k].match(/^        \w/)) {
+                    const attrMatch = lines[k].match(/^        (\w[\w_]*):\s*(.*)/);
+                    if (attrMatch) {
+                      nestedObj[attrMatch[1]] = coerceValue(attrMatch[2].trim());
+                    }
+                    k++;
+                  }
+                  nestedItems.push(nestedObj);
+                } else {
+                  nestedItems.push(coerceValue(nestedItemLine));
+                  k++;
+                }
+              }
+              subKeys[nestedKey] = nestedItems;
+              continue;
             }
-            subKeys[subMatch[1]] = coerce(sv);
+
+            subKeys[nestedKey] = coerceValue(sv);
           }
           k++;
         }
@@ -74,17 +102,12 @@ function parseYaml(text) {
           // First line of block item may have a key: value too
           const firstKeyMatch = itemLine.match(/^(\w[\w_]*):\s*(.*)/);
           if (firstKeyMatch) {
-            let fv = firstKeyMatch[2].trim();
-            if ((fv.startsWith('"') && fv.endsWith('"')) ||
-                (fv.startsWith("'") && fv.endsWith("'"))) {
-              fv = fv.slice(1, -1);
-            }
-            subKeys[firstKeyMatch[1]] = coerce(fv);
+            subKeys[firstKeyMatch[1]] = coerceValue(firstKeyMatch[2].trim());
           }
           items.push(subKeys);
           j = k;
         } else {
-          items.push(coerce(itemLine));
+          items.push(coerceValue(itemLine));
           j++;
         }
       }
@@ -95,13 +118,29 @@ function parseYaml(text) {
         continue;
       }
 
+      const obj = {};
+      j = i + 1;
+      while (j < lines.length && lines[j].match(/^  \w/)) {
+        const objMatch = lines[j].match(/^  (\w[\w_]*):\s*(.*)/);
+        if (objMatch) {
+          obj[objMatch[1]] = coerceValue(objMatch[2].trim());
+        }
+        j++;
+      }
+
+      if (Object.keys(obj).length > 0) {
+        result[key] = obj;
+        i = j;
+        continue;
+      }
+
       result[key] = '';
       i++;
       continue;
     }
 
     // Plain scalar
-    result[key] = coerce(value);
+    result[key] = coerceValue(value);
     i++;
   }
 
@@ -120,7 +159,14 @@ function parseInlineArray(str) {
   }).filter(Boolean);
 }
 
-function coerce(val) {
+function coerceValue(val) {
+  if ((val.startsWith('"') && val.endsWith('"')) ||
+      (val.startsWith("'") && val.endsWith("'"))) {
+    return val.slice(1, -1);
+  }
+  if (val.startsWith('[') && val.endsWith(']')) {
+    return parseInlineArray(val);
+  }
   if (val === 'true') return true;
   if (val === 'false') return false;
   if (val === 'null' || val === '~') return null;

package/lib/github.js

@@ -1,4 +1,5 @@
 import { GITHUB_API } from './constants.js';
+import { CLI_VERSION } from './version.js';
 
 /**
  * Fetch repo info from GitHub API.
@@ -70,7 +71,7 @@ export async function getLatestSha(repo, ref = 'HEAD') {
 function ghHeaders() {
   const headers = {
     'Accept': 'application/vnd.github.v3+json',
-    'User-Agent': 'bananahub-cli/0.1.1'
+    'User-Agent': `bananahub-cli/${CLI_VERSION}`
   };
   if (process.env.GITHUB_TOKEN) {
     headers['Authorization'] = `token ${process.env.GITHUB_TOKEN}`;

package/lib/hub.js

@@ -1,4 +1,5 @@
-import { CLI_VERSION, HUB_API, HUB_CATALOG_URL } from './constants.js';
+import { HUB_API, HUB_CATALOG_URL } from './constants.js';
+import { CLI_VERSION } from './version.js';
 
 export async function fetchHubCatalog() {
   const res = await fetch(HUB_CATALOG_URL, {

package/lib/registry.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { TEMPLATES_DIR, REGISTRY_FILE } from './constants.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { ensurePrimaryTemplatesDir, getTemplateRoots } from './paths.js';
+import { getProviderIds, getSupportedModelIds, normalizeProviders } from './template-schema.js';
 
 /**
  * Rebuild .registry.json by scanning all installed template directories.
@@ -42,7 +43,11 @@ export async function rebuildRegistry() {
           tags: fm.tags || [],
           difficulty: fm.difficulty || 'beginner',
           aspect: fm.aspect || '',
-          models: Array.isArray(fm.models) ? fm.models.map((m) => m.name || m) : [],
+          models: getSupportedModelIds(fm),
+          providers: getProviderIds(fm),
+          provider_matrix: normalizeProviders(fm),
+          capabilities: fm.capabilities || {},
+          prompt_variants: fm.prompt_variants || {},
           source: source?.repo || '',
           version: fm.version || '0.0.0',
           installed_at: source?.installed_at || ''
@@ -55,7 +60,7 @@ export async function rebuildRegistry() {
   }
 
   const registry = {
-    version: '1.0.0',
+    version: '2.0.0',
     generated_at: new Date().toISOString(),
     templates
   };

package/lib/template-schema.js

@@ -0,0 +1,276 @@
+export const VALID_PROVIDER_IDS = [
+  'google-ai-studio',
+  'gemini-compatible',
+  'vertex-ai',
+  'openai',
+  'openai-compatible',
+  'chatgpt-compatible'
+];
+
+export const MODEL_ALIASES = {
+  'nano-banana-pro': 'gemini-3-pro-image-preview',
+  'nano-banana-pro-preview': 'gemini-3-pro-image-preview',
+  'nano-banana-2': 'gemini-3.1-flash-image-preview',
+  'nano-banana-flash': 'gemini-3.1-flash-image-preview',
+  'nano-banana': 'gemini-2.5-flash-image',
+  'nano-banana-1': 'gemini-2.5-flash-image',
+  'gpt-image2': 'gpt-image-2',
+  'gpt image 2': 'gpt-image-2',
+  'gpt-image': 'gpt-image-1',
+  'gpt image': 'gpt-image-1',
+  'gpt5.4': 'gpt-5.4',
+  'gpt 5.4': 'gpt-5.4'
+};
+
+export const MODEL_DISPLAY = {
+  'gpt-image-2': {
+    provider: 'openai',
+    family: 'gpt-image',
+    label: 'GPT Image 2',
+    tier: 'recommended',
+    note: 'Highest-priority default for new high-quality generation when an OpenAI key is available.'
+  },
+  'gemini-3-pro-image-preview': {
+    provider: 'google-ai-studio',
+    family: 'gemini-image',
+    label: 'Gemini 3 Pro Image Preview',
+    tier: 'strong',
+    note: 'Best Nano Banana/Gemini path for template compatibility, editing flows, and conservative prompts.'
+  },
+  'gemini-3.1-flash-image-preview': {
+    provider: 'google-ai-studio',
+    family: 'gemini-image',
+    label: 'Gemini 3.1 Flash Image Preview',
+    tier: 'fast',
+    note: 'Fast Gemini/Nano Banana option for simple templates and lower-cost iteration.'
+  },
+  'gemini-2.5-flash-image': {
+    provider: 'google-ai-studio',
+    family: 'gemini-image',
+    label: 'Gemini 2.5 Flash Image',
+    tier: 'legacy',
+    note: 'Legacy Nano Banana-compatible model.'
+  },
+  'gpt-image-1': {
+    provider: 'openai',
+    family: 'gpt-image',
+    label: 'GPT Image 1',
+    tier: 'fallback',
+    note: 'OpenAI GPT Image fallback where GPT Image 2 is unavailable.'
+  },
+  'gpt-5.4': {
+    provider: 'chatgpt-compatible',
+    family: 'chat-image',
+    label: 'GPT 5.4 Chat Image',
+    tier: 'gateway',
+    note: 'Chat/completions-compatible image path; endpoint behavior is gateway-dependent.'
+  }
+};
+
+export const VALID_MODEL_FAMILIES = [
+  'gemini-image',
+  'gpt-image',
+  'chat-image',
+  'unknown-openai-compatible'
+];
+
+export const VALID_MODEL_QUALITIES = [
+  'best',
+  'good',
+  'ok',
+  'untested',
+  'expected-best'
+];
+
+export const VALID_CAPABILITY_KEYS = [
+  'generation',
+  'edit',
+  'mask_edit'
+];
+
+export function getLegacyModelIds(fm) {
+  if (!Array.isArray(fm?.models)) return [];
+  return fm.models
+    .map((model) => {
+      if (typeof model === 'string') return model;
+      if (model && typeof model === 'object') return model.name || model.id || '';
+      return '';
+    })
+    .filter(Boolean);
+}
+
+export function normalizeProviders(fm) {
+  const providerEntries = Array.isArray(fm?.provider_matrix)
+    ? fm.provider_matrix
+    : (Array.isArray(fm?.providers) && fm.providers.some((provider) => provider && typeof provider === 'object')
+      ? fm.providers
+      : []);
+  if (!providerEntries.length) {
+    return normalizeFlatProviderModelSupport(fm);
+  }
+  return providerEntries
+    .filter((provider) => provider && typeof provider === 'object')
+    .map((provider) => ({
+      id: provider.id || '',
+      family: provider.family || '',
+      models: Array.isArray(provider.models)
+        ? provider.models
+          .filter((model) => model && typeof model === 'object')
+          .map((model) => ({
+            id: model.id || model.name || '',
+            aliases: Array.isArray(model.aliases) ? model.aliases : [],
+            quality: model.quality || 'untested',
+            prompt_variant: model.prompt_variant || ''
+          }))
+        : []
+    }));
+}
+
+function normalizeFlatProviderModelSupport(fm) {
+  const providerIds = Array.isArray(fm?.providers)
+    ? fm.providers.filter((provider) => typeof provider === 'string')
+    : [];
+  const modelIds = Array.isArray(fm?.models)
+    ? fm.models.map((model) => (typeof model === 'string' ? model : model?.id || model?.name || '')).filter(Boolean)
+    : [];
+  if (!providerIds.length || !modelIds.length) return [];
+  return providerIds.map((providerId) => ({
+    id: providerId,
+    family: inferFamily(providerId, modelIds),
+    models: modelIds
+      .filter((modelId) => modelBelongsToProvider(modelId, providerId))
+      .map((modelId) => ({
+        id: canonicalizeModelId(modelId),
+        aliases: [],
+        quality: 'untested',
+        prompt_variant: inferPromptVariant(providerId, modelId)
+      }))
+  })).filter((provider) => provider.models.length);
+}
+
+function inferFamily(providerId, modelIds) {
+  if (providerId === 'openai' || modelIds.some((modelId) => canonicalizeModelId(modelId).startsWith('gpt-image'))) return 'gpt-image';
+  if (providerId === 'chatgpt-compatible') return 'chat-image';
+  if (providerId.includes('gemini') || providerId.includes('google') || providerId === 'vertex-ai') return 'gemini-image';
+  return '';
+}
+
+function inferPromptVariant(providerId, modelId) {
+  const canonical = canonicalizeModelId(modelId);
+  if (canonical.startsWith('gpt-image')) return 'gpt-image';
+  if (providerId === 'chatgpt-compatible' || canonical === 'gpt-5.4') return 'chat-image';
+  if (canonical.startsWith('gemini')) return 'gemini';
+  return '';
+}
+
+function modelBelongsToProvider(modelId, providerId) {
+  const canonical = canonicalizeModelId(modelId);
+  if (providerId === 'openai') return canonical.startsWith('gpt-image');
+  if (providerId === 'chatgpt-compatible') return canonical === 'gpt-5.4';
+  if (providerId === 'google-ai-studio' || providerId === 'gemini-compatible' || providerId === 'vertex-ai') {
+    return canonical.startsWith('gemini');
+  }
+  return true;
+}
+
+export function canonicalizeModelId(value) {
+  const normalized = String(value || '').trim();
+  if (!normalized) return '';
+  return MODEL_ALIASES[normalized.toLowerCase()] || normalized;
+}
+
+export function providerMatches(providerId, requestedProvider) {
+  if (!requestedProvider) return true;
+  return String(providerId || '').toLowerCase() === String(requestedProvider || '').toLowerCase();
+}
+
+export function modelMatches(model, requestedModel) {
+  if (!requestedModel) return true;
+  const canonical = canonicalizeModelId(requestedModel).toLowerCase();
+  const ids = [model?.id, ...(model?.aliases || [])].map((item) => canonicalizeModelId(item).toLowerCase());
+  return ids.includes(canonical);
+}
+
+export function templateSupportsCapability(template, capability) {
+  if (!capability) return true;
+  const capabilities = template?.capabilities || {};
+  return capabilities[capability] === true || capabilities[capability] === 'true';
+}
+
+export function templateSupportsProviderModel(template, { provider = '', model = '', capability = '' } = {}) {
+  if (!templateSupportsCapability(template, capability)) return false;
+  const providers = normalizeProviders(template);
+  if (!providers.length) {
+    const models = getLegacyModelIds(template).map((id) => canonicalizeModelId(id).toLowerCase());
+    return !model || models.includes(canonicalizeModelId(model).toLowerCase());
+  }
+  return providers.some((entry) => {
+    if (!providerMatches(entry.id, provider)) return false;
+    return entry.models.some((entryModel) => modelMatches(entryModel, model));
+  });
+}
+
+export function collectModelSupport(templates) {
+  const support = new Map();
+  for (const template of templates || []) {
+    for (const provider of normalizeProviders(template)) {
+      for (const model of provider.models) {
+        const id = canonicalizeModelId(model.id);
+        if (!id) continue;
+        if (!support.has(id)) {
+          support.set(id, {
+            id,
+            provider: provider.id,
+            family: provider.family,
+            aliases: new Set(),
+            qualities: new Set(),
+            prompt_variants: new Set(),
+            templates: [],
+            capabilities: new Set()
+          });
+        }
+        const entry = support.get(id);
+        for (const alias of model.aliases || []) entry.aliases.add(alias);
+        if (model.quality) entry.qualities.add(model.quality);
+        if (model.prompt_variant) entry.prompt_variants.add(model.prompt_variant);
+        entry.templates.push(template.id);
+        for (const [key, value] of Object.entries(template.capabilities || {})) {
+          if (value === true || value === 'true') entry.capabilities.add(key);
+        }
+      }
+    }
+  }
+  return [...support.values()].map((entry) => ({
+    ...entry,
+    aliases: [...entry.aliases],
+    qualities: [...entry.qualities],
+    prompt_variants: [...entry.prompt_variants],
+    capabilities: [...entry.capabilities],
+    template_count: entry.templates.length
+  }));
+}
+
+export function getProviderModelIds(fm) {
+  return normalizeProviders(fm)
+    .flatMap((provider) => provider.models.map((model) => model.id))
+    .filter(Boolean);
+}
+
+export function getSupportedModelIds(fm) {
+  return Array.from(new Set([...getLegacyModelIds(fm), ...getProviderModelIds(fm)]));
+}
+
+export function getProviderIds(fm) {
+  return normalizeProviders(fm)
+    .map((provider) => provider.id)
+    .filter(Boolean);
+}
+
+export function hasPromptVariant(content, variantId) {
+  if (!variantId || variantId === 'base' || variantId === 'default') return true;
+  const escaped = variantId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return (
+    new RegExp(`^##\\s+Prompt Template:\\s*${escaped}\\s*$`, 'im').test(content) ||
+    new RegExp(`^#{2,4}\\s+Provider Variant:\\s*${escaped}\\s*$`, 'im').test(content)
+  );
+}

package/lib/validate.js

@@ -2,6 +2,15 @@ import { readFile, access, readdir } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { parseFrontmatter } from './frontmatter.js';
 import { VALID_PROFILES, VALID_DIFFICULTIES, VALID_TEMPLATE_TYPES } from './constants.js';
+import {
+  VALID_CAPABILITY_KEYS,
+  VALID_MODEL_FAMILIES,
+  VALID_MODEL_QUALITIES,
+  VALID_PROVIDER_IDS,
+  getSupportedModelIds,
+  hasPromptVariant,
+  normalizeProviders
+} from './template-schema.js';
 
 const SAMPLE_FILE_PATTERN = /^sample-[a-z0-9.]+(?:-[a-z0-9.]+)*-\d{2}\.(jpg|jpeg|png|webp)$/i;
 const DEFAULT_TEMPLATE_TYPE = 'prompt';
@@ -70,10 +79,12 @@ export async function validateTemplate(dirPath) {
     warnings.push('No license declared — add `license: CC-BY-4.0` or another SPDX/CC identifier');
   }
 
-  if (!fm.models || !Array.isArray(fm.models) || fm.models.length === 0) {
-    warnings.push('No models listed — users won\'t know which models are tested');
+  const supportedModelIds = getSupportedModelIds(fm);
+  if (supportedModelIds.length === 0) {
+    warnings.push('No models/providers listed — users won\'t know which models or providers are supported');
   }
 
+  validateProviderMetadata(fm, content, errors, warnings);
   validateBody(content, templateType, warnings);
   await validateLicenseFiles(dirPath, warnings);
   await validateSamplesDir(dirPath, templateType, warnings);
@@ -88,6 +99,63 @@ export async function validateTemplate(dirPath) {
   };
 }
 
+function validateProviderMetadata(fm, content, errors, warnings) {
+  const providers = normalizeProviders(fm);
+  const hasProviderMatrix = Array.isArray(fm.providers) && fm.providers.length > 0;
+
+  if (!hasProviderMatrix) {
+    warnings.push('No provider matrix found — add `providers` for schema v2 multi-model compatibility');
+    return;
+  }
+
+  for (const provider of providers) {
+    if (!provider.id) {
+      errors.push('Provider entry is missing `id`');
+      continue;
+    }
+
+    if (!VALID_PROVIDER_IDS.includes(provider.id)) {
+      warnings.push(`Provider "${provider.id}" is not a known BananaHub provider id`);
+    }
+
+    if (provider.family && !VALID_MODEL_FAMILIES.includes(provider.family)) {
+      warnings.push(`Provider "${provider.id}" has unknown family "${provider.family}"`);
+    }
+
+    if (!provider.models.length) {
+      errors.push(`Provider "${provider.id}" must list at least one model`);
+      continue;
+    }
+
+    for (const model of provider.models) {
+      if (!model.id) {
+        errors.push(`Provider "${provider.id}" has a model entry without \`id\``);
+        continue;
+      }
+
+      if (!VALID_MODEL_QUALITIES.includes(model.quality)) {
+        warnings.push(`Model "${model.id}" has unusual quality "${model.quality}"`);
+      }
+
+      if (!model.prompt_variant) {
+        warnings.push(`Model "${model.id}" should declare prompt_variant to prevent cross-provider prompt misuse`);
+      } else if (!hasPromptVariant(content, model.prompt_variant)) {
+        errors.push(`Model "${model.id}" references missing prompt variant "${model.prompt_variant}"`);
+      }
+    }
+  }
+
+  if (!fm.capabilities || typeof fm.capabilities !== 'object' || Array.isArray(fm.capabilities)) {
+    warnings.push('No capabilities object found — add generation/edit/mask_edit flags for runtime routing');
+  } else {
+    for (const key of Object.keys(fm.capabilities)) {
+      if (!VALID_CAPABILITY_KEYS.includes(key)) {
+        warnings.push(`Unknown capability "${key}"`);
+      }
+    }
+  }
+}
+
 function validateBody(content, templateType, warnings) {
   if (templateType === 'workflow') {
     const requiredSections = ['## Goal', '## Inputs', '## Steps', '## Prompt Blocks'];
@@ -168,12 +236,20 @@ async function validateSampleMetadata(dirPath, fm, warnings) {
       warnings.push(`Sample file "${sample.file}" should follow sample-{model-short}-{nn}.ext naming`);
     }
 
+    if (!sample.provider) {
+      warnings.push(`Sample "${sample.file}" is missing \`provider\``);
+    }
+
     if (!sample.model) {
       warnings.push(`Sample "${sample.file}" is missing \`model\``);
     } else if (!fileNameIncludesModel(fileName, sample.model)) {
       warnings.push(`Sample file "${sample.file}" should include the generating model shorthand for "${sample.model}"`);
     }
 
+    if (!sample.prompt_variant) {
+      warnings.push(`Sample "${sample.file}" is missing \`prompt_variant\``);
+    }
+
     if (!sample.prompt) {
       warnings.push(`Sample "${sample.file}" is missing \`prompt\``);
     }

package/lib/version.js

@@ -0,0 +1,8 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageJsonPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+
+export const CLI_VERSION = packageJson.version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bananahub",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Template manager for BananaHub Skill — installable Gemini workflow modules",
   "type": "module",
   "bin": {