bananahub 0.1.1 → 0.1.3

package/README.md

@@ -1,9 +1,17 @@
 # bananahub
 
-Template manager for [BananaHub Skill](https://github.com/bananahub-ai/banana-hub-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/banana-hub-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`
 
@@ -131,12 +157,24 @@ bananahub registry rebuild
 
 ## Template Format
 
-A valid BananaHub template directory must contain a `template.md` file with YAML frontmatter at its root. Templates may be `type: prompt` or `type: workflow`, and may live as:
+A valid BananaHub template directory must contain a `template.md` file with YAML frontmatter at its root. Published templates should declare a frontmatter `license` such as `CC-BY-4.0` and include a repo `LICENSE` file. Templates may be `type: prompt` or `type: workflow`, and may live as:
 
 - a single-template repository with `template.md` at repo root
 - a multi-template repository with `bananahub.json` plus per-template subdirectories
 - a known collection layout such as `references/templates/<template-id>/template.md`
 
+## Contributing
+
+Code, docs, and tests contributed to this repo are accepted under the repo's MIT license.
+
+Sign off each commit with the Developer Certificate of Origin:
+
+```bash
+git commit -s -m "feat: your change"
+```
+
+Template repos created with `bananahub init` default to `CC-BY-4.0` for template content. If you publish community templates, keep the template frontmatter `license` field and the repo `LICENSE` file in sync.
+
 ## License
 
-MIT
+Code in this repo is licensed under MIT.

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/banana-hub-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];
@@ -43,6 +44,7 @@ export async function infoCommand(args) {
     ['Type', fm.type || 'prompt'],
     ['Version', fm.version || '-'],
     ['Author', fm.author || '-'],
+    ['License', fm.license || '-'],
     ['Profile', fm.profile || '-'],
     ['Aspect', fm.aspect || '-'],
     ['Difficulty', fm.difficulty || '-'],
@@ -57,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})` : '';
@@ -65,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}`));
@@ -72,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,40 @@ 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 should name the provider, exact model, and prompt variant used.
+
+## License
+
+This template content is published under CC BY 4.0. Keep the frontmatter \`license\` value and the repo \`LICENSE\` file aligned. Only publish samples and copy that you can redistribute.
+`;
+}
+
+function buildTemplateLicenseFile() {
+  return `Creative Commons Attribution 4.0 International
+
+SPDX-License-Identifier: CC-BY-4.0
+
+This template content is licensed under the Creative Commons Attribution 4.0 International License.
+
+You may share and adapt this material for any purpose, including commercial use,
+as long as you give appropriate credit, provide a link to the license, and indicate
+if changes were made.
 
-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\`.
+License text:
+https://creativecommons.org/licenses/by/4.0/
 `;
 }
 
@@ -166,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: []`;
 
@@ -176,6 +212,7 @@ id: ${id}
 title: ${title}
 title_en: ${titleEn}
 author: your-github-username
+license: CC-BY-4.0
 version: 1.0.0
 profile: ${profile}
 tags: []
@@ -186,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}
@@ -199,15 +262,17 @@ ${buildTemplateBody(type)}
   await writeFile(join(outDir, 'template.md'), templateMd);
   await writeFile(join(outDir, 'samples', '.gitkeep'), '');
   await writeFile(join(outDir, 'README.md'), buildReadme(titleEn, id, profile, type));
+  await writeFile(join(outDir, 'LICENSE'), buildTemplateLicenseFile());
 
   console.log(green(`\n  Created: ${bold(id)}/`));
   console.log(dim(`    ${id}/template.md`));
   console.log(dim(`    ${id}/samples/.gitkeep`));
   console.log(dim(`    ${id}/README.md`));
+  console.log(dim(`    ${id}/LICENSE`));
   console.log(cyan('\n  Next steps:'));
   console.log(dim(`    1. Edit template.md — add your ${type === 'workflow' ? 'workflow sections and prompt blocks' : 'prompt and variables'}`));
   console.log(dim('    2. Add sample images to samples/ and include the model in each filename'));
-  console.log(dim('    3. Update README.md with verified/supported models and sample mappings'));
+  console.log(dim('    3. Update README.md with verified/supported models, sample mappings, and any license notes'));
   console.log(dim('    4. Create a GitHub repo and push'));
   console.log(dim('    5. Others install: npx bananahub add <user>/' + id));
   console.log();

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();
+}