{ "schema_version": "1.0.0", "name": "BananaHub Agent Initialization", "updated": "2026-05-15", "stable_urls": { "json": "https://bananahub.ai/agent-init.json", "markdown": "https://bananahub.ai/agent-init.md", "llms_txt": "https://bananahub.ai/llms.txt", "catalog_json": "https://bananahub.ai/catalog.json" }, "skill": { "name": "bananahub", "repo": "https://github.com/bananahub-ai/bananahub-skill", "user_command": "/bananahub", "install_commands": [ { "host": "open-agent-skills", "command": "npx skills add https://github.com/bananahub-ai/bananahub-skill --skill bananahub" }, { "host": "claude-code", "command": "claude skill install https://github.com/bananahub-ai/bananahub-skill" } ] }, "scope": { "does": [ "install BananaHub Skill when the host agent supports the listed install command", "diagnose local BananaHub provider configuration", "create or update BananaHub provider profiles in the local BananaHub config", "collect or route API-key entry according to user choice, then persist it in the local BananaHub config", "install missing Python runtime packages reported by config doctor after user consent", "validate provider-backed, host-native, or prompt-only runtime mode" ], "does_not": [ "run SQL or database migrations", "modify application database schemas", "upgrade Cloudflare Worker, KV, API, CLI, template repositories, or other BananaHub components", "update an existing BananaHub installation beyond what the selected host install command normally does", "run paid image generation without explicit user consent" ], "existing_install_policy": "If BananaHub Skill is already installed, diagnose first and preserve any valid provider/profile/model configuration. Do not reinstall or upgrade unrelated components unless the user explicitly asks for that operation.", "component_update_policy": "Treat SQL/database changes, service upgrades, CLI upgrades, template repository updates, and platform deployment changes as separate maintenance tasks outside this initialization contract." }, "agent_contract": { "secret_policy": "ask_user_to_choose_direct_agent_entry_or_local_placeholder_command", "direct_agent_entry_allowed": true, "preferred_secret_entry": [ "agent_session_field_collection_with_api_key_stdin_when_user_explicitly_allows", "terminal_quickset_command_with_placeholder", "human_terminal_init_wizard_fallback" ], "interactive_command_policy": "Agents must not assume they can run TTY prompts. init --wizard is a human-terminal fallback, not the default agent path.", "first_human_question": "Which image channel do you already have?", "default_provider": "openai-compatible", "default_profile": "gpt", "default_model": "gpt-image-2", "preserve_existing_valid_config": true, "persistent_profile_precedence": true, "env_override_flag": "BANANAHUB_ENV_OVERRIDE", "env_default_behavior": "Environment variables fill missing profile fields by default and override persisted profile fields only when BANANAHUB_ENV_OVERRIDE=1 is set.", "paid_generation_requires_explicit_consent": true, "diagnose_before_provider_call": true }, "config_profile_contract": { "path": "~/.config/bananahub/config.json", "selection": "Use default_profile unless BANANAHUB_PROFILE or --profile selects another profile.", "precedence": [ "--config ", "selected profile from ~/.config/bananahub/config.json", "environment variables as fallback values for fields missing from the selected profile" ], "environment_override": "Set BANANAHUB_ENV_OVERRIDE=1 only for deliberate temporary environment overrides.", "shape": { "default_profile": "gpt", "profiles": { "gpt": { "provider": "openai-compatible", "openai_base_url": "https://example.com/v1", "openai_api_key": "", "model": "gpt-image-2" }, "nano": { "provider": "google-ai-studio", "api_key": "", "model": "gemini-3-pro-image-preview" } } }, "profile_defaults": { "openai-compatible": "gpt", "openai": "gpt", "google-ai-studio": "nano", "gemini-compatible": "nano", "vertex-ai": "vertex", "chatgpt-compatible": "chat" } }, "flow": [ { "step": "diagnose", "command": "python3 {baseDir}/scripts/bananahub.py config doctor --json", "parse_fields": [ "status", "provider", "profile", "missing_fields", "missing_dependencies", "requires_user_secret", "safe_to_autofix", "suggested_commands", "suggested_commands_stdin", "config_path", "secret_entry_modes", "precedence", "ignored_config_sources", "env_shadowed_config_sources", "agent_notes" ] }, { "step": "stop_if_ready", "condition": "diagnosis.status == \"ok\"", "next_action": "proceed_to_bananahub_work" }, { "step": "collect_connection_fields", "condition": "diagnosis.status == \"needs_setup\"", "rule": "Ask only for provider-required fields. If the user chooses direct agent entry or already pasted values, persist the API key with config quickset --api-key-stdin. If the user does not want secrets in chat, provide the matching quickset command with placeholders for the user's local terminal." }, { "step": "persist_provider_profile", "condition": "required connection fields are available", "command_source": "providers[*].quickset_command", "stdin_command_source": "providers[*].quickset_stdin_command", "writes": "~/.config/bananahub/config.json" }, { "step": "dependency_repair", "condition": "diagnosis.missing_dependencies.length > 0 && user_allows_local_package_install", "command_source": "diagnosis.dependency_install_command", "pep668_policy": "do_not_add_break_system_packages_automatically" }, { "step": "human_terminal_fallback", "condition": "user_wants_manual_interactive_setup", "command": "python3 {baseDir}/scripts/bananahub.py init --wizard", "rule": "Only ask the human to run this in a real terminal; do not use it as the agent automation path." }, { "step": "non_paid_validation", "commands": [ "python3 {baseDir}/scripts/bananahub.py init --skip-test --json", "python3 {baseDir}/scripts/bananahub.py config show", "python3 {baseDir}/scripts/bananahub.py check-mode --pretty" ] }, { "step": "paid_smoke_test", "condition": "user_explicitly_consents_to_spend_generation_quota", "command_source": "smoke_tests.gpt_image_2_generation.command" } ], "providers": [ { "id": "openai-compatible", "label": "OpenAI-compatible gateway", "profile": "gpt", "default_model": "gpt-image-2", "requires": [ "api_key", "base_url" ], "quickset_command": "python3 {baseDir}/scripts/bananahub.py config quickset --provider openai-compatible --profile gpt --default-profile --base-url \"\" --api-key \"\" --model gpt-image-2", "quickset_stdin_command": "python3 {baseDir}/scripts/bananahub.py config quickset --provider openai-compatible --profile gpt --default-profile --base-url \"\" --api-key-stdin --model gpt-image-2" }, { "id": "openai", "label": "OpenAI official GPT Image API", "profile": "gpt", "default_model": "gpt-image-2", "requires": [ "api_key" ], "quickset_command": "python3 {baseDir}/scripts/bananahub.py config quickset --provider openai --profile gpt --default-profile --api-key \"\" --model gpt-image-2", "quickset_stdin_command": "python3 {baseDir}/scripts/bananahub.py config quickset --provider openai --profile gpt --default-profile --api-key-stdin --model gpt-image-2" }, { "id": "google-ai-studio", "label": "Google AI Studio / Gemini", "profile": "nano", "default_model": "gemini-3-pro-image-preview", "requires": [ "api_key" ], "quickset_command": "python3 {baseDir}/scripts/bananahub.py config quickset --provider google-ai-studio --profile nano --default-profile --api-key \"\" --model gemini-3-pro-image-preview", "quickset_stdin_command": "python3 {baseDir}/scripts/bananahub.py config quickset --provider google-ai-studio --profile nano --default-profile --api-key-stdin --model gemini-3-pro-image-preview" }, { "id": "gemini-compatible", "label": "Gemini-compatible gateway", "profile": "nano", "default_model": "gemini-3-pro-image-preview", "requires": [ "api_key", "base_url" ], "quickset_command": "python3 {baseDir}/scripts/bananahub.py config quickset --provider gemini-compatible --profile nano --default-profile --base-url \"\" --api-key \"\" --model gemini-3-pro-image-preview", "quickset_stdin_command": "python3 {baseDir}/scripts/bananahub.py config quickset --provider gemini-compatible --profile nano --default-profile --base-url \"\" --api-key-stdin --model gemini-3-pro-image-preview" }, { "id": "vertex-ai", "label": "Vertex AI", "profile": "vertex", "default_model": "gemini-3-pro-image-preview", "requires": [ "project", "location" ], "quickset_command": "python3 {baseDir}/scripts/bananahub.py config quickset --provider vertex-ai --profile vertex --default-profile --auth-mode adc --project \"\" --location global" }, { "id": "chatgpt-compatible", "label": "ChatGPT-compatible image endpoint", "profile": "chat", "default_model": "gpt-5.4", "requires": [ "api_key", "base_url" ], "quickset_command": "python3 {baseDir}/scripts/bananahub.py config quickset --provider chatgpt-compatible --profile chat --default-profile --base-url \"\" --api-key \"\" --model gpt-5.4", "quickset_stdin_command": "python3 {baseDir}/scripts/bananahub.py config quickset --provider chatgpt-compatible --profile chat --default-profile --base-url \"\" --api-key-stdin --model gpt-5.4" } ], "diagnosis_contract": { "primary_command": "python3 {baseDir}/scripts/bananahub.py config doctor --json", "ready_status": "ok", "needs_setup_status": "needs_setup", "precedence_field": "precedence", "ignored_config_sources_policy": "treat_as_informational_unless_it_explains_a_failure", "env_shadowed_config_sources_policy": "treat_as informational; these env vars were ignored because the selected persisted profile already defines that field", "dependency_policy": { "install_command_field": "dependency_install_command", "pep668_error": "externally-managed-environment", "pep668_action": "ask_user_to_choose_agent_python_environment_venv_or_os_package_manager" } }, "smoke_tests": { "non_paid": [ "python3 {baseDir}/scripts/bananahub.py init --skip-test --json", "python3 {baseDir}/scripts/bananahub.py check-mode --pretty" ], "gpt_image_2_generation": { "requires_explicit_user_consent": true, "command": "BANANAHUB_PROFILE=gpt python3 {baseDir}/scripts/bananahub.py generate \"Create a cute sticker of a tiny cheerful robot holding a banana, rounded kawaii vector style, thick clean outlines, soft pastel colors, plain white background, no text.\" --model gpt-image-2 --aspect 1:1 --no-fallback --output /tmp/bananahub-gpt-image-2-smoke-test.png", "expected": { "status": "ok", "actual_model": "gpt-image-2", "output": "readable_image_file" } } }, "after_setup": { "template_discovery_order": [ "https://bananahub.ai/llms.txt", "https://bananahub.ai/catalog.json", "https://bananahub.ai/agent-catalog.md" ] }, "handoff_usage": { "instruction": "Read https://bananahub.ai/agent-init.json and initialize BananaHub according to it.", "human_readable_fallback": "https://bananahub.ai/agent-init.md" } }