Onboarding

Onboarding should get the user to a working Bestie quickly. It creates local config, character files, prompt files, env entries, and an optional provider test without forcing the user to configure every future subsystem on day one.

Fast first magic beats complete first bureaucracy. Không ai muốn cài bạn thân AI mà bị hỏi như khai hải quan.

Goal

Onboarding v1 should cover:

1. Character basics.
2. Memory write policy.
3. LLM provider setup.
4. Optional provider test.
5. Terminal chat handoff.

Telegram, Zalo, cron, MCP, voice, and local UI can be follow-up commands after the core runtime passes Doctor.

Command

bestie onboard
bestie onboard --skip-provider-test

Use --skip-provider-test for offline setup, smoke tests, slow providers, or temporarily unavailable providers. It still creates config, env, character, prompt, and log files.

Flow

Welcome
  -> choose character name
  -> choose what Bestie calls the owner
  -> choose language and tone
  -> choose memory write policy
  -> choose LLM provider
  -> enter provider settings and API key when needed
  -> write config and env files
  -> generate character files and system prompt
  -> test LLM unless --skip-provider-test is set
  -> suggest terminal chat and Doctor

Character questions

Onboarding may ask:

• What should your bestie be called?
• What should it call you?
• Which language mode should it use: Vietnamese, English, or mixed?
• Which vibe preset should it start with?
• Roast level from 1-10.
• Warmth level from 1-10.
• Bluntness level from 1-10.
• Emoji level: none, light, or expressive.
• Topics it should never joke about.

The generated prompt should keep Bestie funny, sharp, warm, and practical while preserving safety boundaries.

Memory policy question

Onboarding writes memory.writePolicy:

Policy	Behavior
ask	Queue allowed non-secret memories for owner approval. Good default.
allow	Store allowed non-secret memories directly. Faster, but requires trust.
deny	Reject model-requested memory writes. Useful for private or temporary setups.

Secrets, tokens, payment details, and raw credentials must never be stored as memory.

LLM provider setup

Supported setup directions include:

• Anthropic Claude
• ChatGPT/OpenAI
• Groq
• OpenRouter
• Custom OpenAI-compatible
• Custom Anthropic-compatible
• Ollama
• Gemini API key
• Antigravity appears as a future OAuth provider, but OAuth setup is not implemented yet

Required values depend on provider:

• API-key providers need an environment variable name and key value.
• HTTP providers need a base URL.
• Native Gemini API-key mode uses GEMINI_API_KEY and does not need baseUrl.
• Local Ollama uses local endpoint config and does not need an API key.

Secrets are written to ~/.bestie/.env. Non-secret settings are written to ~/.bestie/config.json.

Validation

Onboarding should validate:

• runtime paths are writable
• config can be written
• env can be written without echoing secrets
• character prompt is non-empty
• selected provider settings are structurally valid
• provider test result is explained when it runs

A failed provider test should not delete local files. The user can fix provider settings later and rerun Doctor or bestie llm test.

Follow-up commands

After onboarding:

bestie doctor
bestie chat
bestie ui
bestie channels telegram setup
bestie channels zalo setup
bestie memory status
bestie llm test --model <provider/model>

Run Doctor before starting long-lived channels or services.

Principle

Do not ask users to configure the whole universe before they feel the product. The first run should prove Bestie can talk, remember safely, and call the configured provider. Everything else can wait until the user trusts the local runtime.