# Welcome to BonzAI

BonzAI is a private AI workspace for creating, training, and automating without surrendering your work to a centralized platform.

Most AI products ask you to send prompts, files, images, business ideas, and training data to someone else's servers. BonzAI takes the opposite path: useful AI begins on your device and remains under your control.

## The Problem BonzAI Solves

Cloud AI is convenient, but it separates users from their data, models, and operating context. Traditional local model tools protect privacy but often stop at a prompt box.

BonzAI connects the work around the model:

```
private context -> structured data -> generation -> training -> automation
```

Captured context can become a reusable dataset. A dataset can improve a model. A model can support a companion or an agentic business team. Useful work accumulates instead of disappearing into isolated chats.

| Option              | What you get                                                  | What is missing                                                       |
| ------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------- |
| Cloud AI apps       | Powerful models and polished UX                               | Local control, privacy, and inspectable infrastructure                |
| Local model runners | Private local inference                                       | Connected capture, memory, training, agents, and business workflows   |
| BonzAI              | One private loop where work can accumulate, improve, and ship | Hardware still matters, so BonzAI spans browser and desktop workflows |

## The Three Products

| Product            | Plain-English purpose                                                                                               |
| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
| **BonzAI Web**     | Try private browser AI and find the right BonzAI workflow.                                                          |
| **BonzAI+**        | Chat about pages, capture text and images, follow video, generate images, and build datasets in the browser.        |
| **BonzAI Desktop** | Generate across modalities, train models, run companions, and deploy agentic business teams from a local workspace. |

## What You Can Do

* Chat privately with local AI.
* Generate images, audio, music, video, and interactive 3D scenes.
* Capture useful text and images while browsing.
* Turn captured material into structured datasets.
* Import datasets into Desktop for local training and fine-tuning.
* Create companions with persistent identity and memory.
* Operate agentic business teams that prepare, execute, review, and remember real work.

## Sovereign Ownership Layer

Wallets, `$BONZAI`, minting, staking, markets, rewards, and provider economics are part of the BonzAI architecture. They connect private creation to portable identity, public settlement, contributor attribution, and programmable revenue.

Local inference remains private. Onchain actions remain explicit: users choose when to publish, mint, stake, pay, claim, or grant an agent permission.

## Start Here

* New users: [Choose Your BonzAI](/start-here/getting-started)
* First session: [Your First 10 Minutes](/start-here/first-10-minutes)
* Business automation: [Agentic Teams for Business](/business-automation/zero-human-company)
* Ownership and network economy: [Web3 & Onchain Economy](/ownership-and-network/web3)


# Choose Your BonzAI

You do not need to understand AI models, blockchains, or computer hardware to begin. Start with what you want to do.

## I want to try BonzAI now

Open **BonzAI Web** at [bonzai.sh](https://bonzai.sh). It is the quickest introduction and can run private browser chat on supported desktop browsers.

Choose this when you want to:

* ask a question without installing the full studio;
* understand what BonzAI can do;
* find the correct Desktop download;
* install the BonzAI+ browser assistant.

## I want BonzAI beside every website

Install **BonzAI+** in a Chromium-based desktop browser. It opens in the browser side panel.

Choose this when you want to:

* chat normally or ask about a selected image or piece of text;
* save useful material from webpages;
* understand a video while it plays;
* generate images inside the browser;
* prepare clean datasets for BonzAI Desktop.

## I want the complete private AI studio

Install **BonzAI Desktop**.

Choose this when you want to:

* chat with a wider choice of local models;
* generate images, speech, music, video, and interactive 3D scenes;
* train or uncensor compatible models;
* build persistent companion memory;
* run agentic business teams;

Ownership, publishing, and provider features are available alongside the creative workflow when you are ready to use them.

## Do I need a wallet?

No. A wallet is not needed for normal private creation. It is used when you choose an onchain action such as publishing, minting, staking, paying a provider, or claiming revenue.

## Do I need to download a model?

Usually, yes. A model is the part that performs the AI work. BonzAI downloads it to your device the first time you select it, then reuses the cached copy.

Think of this like downloading an offline map: the first use takes longer, but later use does not need to fetch the same map again.

## Recommended path for a new user

1. Visit BonzAI Web and ask one question.
2. Install BonzAI+ if you spend time researching, watching videos, or collecting examples online.
3. Install BonzAI Desktop when you want stronger models, media generation, memory, training, companions, or business teams.
4. Connect a wallet when you want to publish, mint, stake, use paid peer compute, or participate in the contributor economy.

Continue with [Your First 10 Minutes](/start-here/first-10-minutes).


# Your First 10 Minutes

This walkthrough gets you from installation to a useful result without technical setup.

## Minute 1: choose one simple outcome

Pick something small and real:

* summarize a document;
* draft a customer reply;
* create an image concept;
* capture a useful webpage image;
* ask a companion to remember a preference.

Starting with a real task makes model choices much easier to understand.

## Minutes 2–4: let BonzAI prepare

When BonzAI asks to download a model:

1. Read the model's purpose and hardware estimate.
2. Choose a smaller or faster model for your first attempt.
3. Keep BonzAI open while the progress bar completes.

The download is stored locally. It should not repeat every time you launch the product.

## Minutes 5–7: make your first result

### In BonzAI Web

Type a question and send it. If local browser AI is unavailable on your device, BonzAI explains which product can complete the task.

### In BonzAI+

Open **Chat** and ask anything. To ask about a webpage image or text passage, use the **BonzAI+** capture button on the page, then return to Chat.

### In BonzAI Desktop

Open **Chat**, choose the recommended local model, and describe the outcome you want. You can change models later without losing the purpose of your conversation.

## Minutes 8–10: make the result reusable

BonzAI is most useful when work does not disappear after one answer.

* Keep the conversation if it contains useful context.
* Save a generation to history.
* In BonzAI+, save a captured example in **Dataset** mode.
* Give a companion a fact worth remembering.
* Export or mint only when you deliberately want the work to leave its private state.

## A good first prompt

Use this shape:

> I want to achieve **\[outcome]**. The audience is **\[person]**. Use **\[source/context]**. The result should feel **\[tone]** and must include **\[important constraints]**.

Example:

> I want to reply to a late-paying customer. The audience is a long-term client. Be warm but clear, mention invoice 1042, and ask for payment by Friday without sounding threatening.

## If the result is slow

* Pick a smaller model.
* Close other memory-heavy applications.
* Reduce image or video resolution.
* Use a faster generation mode.
* Let an active generation finish before starting another large one.

Slower hardware does not prevent you from using BonzAI. It changes which model and quality setting will feel comfortable.


# Install BonzAI Desktop

## Before you begin

You need a supported desktop or laptop, enough free storage for the app and at least one model, and a stable connection for the first download.

## Install

1. Visit [bonzai.sh](https://bonzai.sh) on the computer where you want to use BonzAI.
2. Choose the download for your operating system.
3. Open the downloaded installer.
4. Follow your operating system's normal installation prompts.
5. Launch BonzAI Desktop.

Only download BonzAI from an official BonzAI page or release link.

## First launch

BonzAI starts its private AI services in the background. During this short preparation period, the app may show a starting status.

Then:

1. Open **Chat**.
2. Choose a recommended model that fits your computer.
3. Confirm the first model download.
4. Wait for the download to finish.
5. Send your first message.

## Operating-system security messages

Your operating system may ask you to confirm that you trust the application or allow local network access.

* Confirm only if you downloaded BonzAI from an official source.
* Local network permission is useful for optional provider or device-to-device features.
* BonzAI's normal local generation does not mean your prompts are being uploaded to a cloud AI service.

## Updating BonzAI

Install official updates when notified. Model files are stored separately from the application where possible, so an application update should not require every model to be downloaded again.

## Uninstalling

Removing the application and deleting model/data folders are different actions. Before deleting local data, export any conversations, contribution packs, companion identities, memories, or generated work you want to keep.


# Install BonzAI+

BonzAI+ is a desktop browser extension. It works best in Chromium-based browsers that support extension side panels and local browser AI features.

## Install from a browser store

1. Open the official BonzAI+ store listing from [bonzai.sh](https://bonzai.sh).
2. Choose **Add to browser**.
3. Confirm the permissions shown by the browser.
4. Pin the BonzAI+ toolbar icon if you want one-click access.
5. Open the extension and allow its first model download when requested.

## Open the side panel

Click the round BonzAI+ toolbar icon. The assistant opens beside the current webpage, so you can keep reading or watching while using it.

## Capture on pages that were already open

Browsers cannot always inject a newly installed extension into tabs that existed before installation. Reload those tabs once. New tabs work normally.

## Permissions explained

* **Current page access** lets BonzAI+ identify text, images, and page context you deliberately capture.
* **Side panel access** keeps the assistant visible beside the page.
* **Tab or screen capture** is requested only when you start Live analysis.
* **Downloads** lets you save generated images and exported contribution packs.

BonzAI+ does not need a wallet for chat, capture, Live, Imagine, or private dataset work.

## Mobile browsers

Mobile browsers do not currently provide the same extension side-panel and local model environment as desktop Chromium browsers. Use BonzAI Web for the mobile-friendly product experience and return to BonzAI+ on a supported desktop browser.


# Hardware & Model Choices

BonzAI runs AI on your device. A more powerful computer can use larger models or finish media generation faster, but modest computers can still use smaller models and browser features.

## The simple rule

* **8 GB memory:** start with small chat models and lighter browser workflows.
* **16 GB memory:** comfortable everyday chat, lighter image/audio work, and more model choice.
* **24–32 GB memory:** larger language models, stronger image workflows, and better multitasking.
* **High-end Apple Silicon or a dedicated NVIDIA GPU:** best for large models, video, training, and high-resolution media.

## Storage

Models can be much larger than the application.

* Keep at least 10 GB free for a basic setup.
* Keep 50 GB or more free if you want several language and media models.
* Video, training checkpoints, and generation history can use additional space.

BonzAI shows download size before or during model installation. You can remove models you no longer use.

## Choosing a language model

| Your priority                       | Choose                                       |
| ----------------------------------- | -------------------------------------------- |
| Fast answers and low memory use     | Small model                                  |
| Everyday quality                    | Medium model                                 |
| Difficult reasoning or long writing | Larger model that fits your hardware         |
| Programming                         | A coder-focused model                        |
| Unrestricted local experimentation  | A compatible abliterated model, where lawful |

Quantization reduces model size. Lower-bit versions use less memory and usually run faster, but may lose some accuracy. BonzAI's recommendations are designed to make this tradeoff understandable.

## Choosing media settings

* Begin with SD or HD image resolution.
* Use Turbo/Fast while exploring ideas.
* Switch to higher quality once the prompt is working.
* Generate shorter videos before committing to long clips.
* Close unused large models before training or video generation.

## Apple, NVIDIA, and CPU-only devices

BonzAI selects compatible acceleration when available:

* Apple Silicon uses unified memory and Apple GPU acceleration.
* NVIDIA systems use CUDA-capable paths where supported.
* Other systems can use CPU or available fallback acceleration, but large media models may be slow.

The app's hardware information helps you choose; you do not need to configure acceleration manually.


# Privacy & Downloads

## What “local” means

For local generation, the model runs on your device. Your prompt is processed by that local model instead of being sent to a hosted AI provider.

Your work leaves the private device boundary only when you deliberately use a feature that requires it, such as:

* opening a normal website or third-party connector;
* asking a P2P provider to perform inference;
* publishing metadata or media;
* minting or sending a blockchain transaction;
* sharing or exporting a file.

## Wallet functions

Wallets provide economic identity, publishing, settlement, rewards, companion permissions, and provider activity across BonzAI.

BonzAI never needs your seed phrase. Your wallet asks you to approve transactions.

Before approving, check:

* the network;
* the contract or recipient;
* the amount;
* whether the action is a payment, approval, stake, mint, or claim.

## Model downloads

Models come from their published repositories and are cached locally. The model license shown in Desktop explains allowed uses. Some models permit commercial use; others impose restrictions.

## Publishing is a choice

Private generations are not automatically public. Minting, registry publication, marketplace discovery, and contribution publishing are explicit actions. NSFW generations are not eligible for public marketplace discovery.

## Dataset responsibility

Only collect and train on material you are allowed to use. BonzAI records source, license, permissions, and provenance to help, but the user remains responsible for lawful collection and publication.


# The BonzAI Suite

BonzAI is one continuous local AI experience across browser and desktop.

## The three products

| Product            | Plain-English job                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| **BonzAI Web**     | Meet BonzAI and use private browser chat where supported                                             |
| **BonzAI+**        | Work with the page beside you: chat, capture, understand video, generate images, and curate datasets |
| **BonzAI Desktop** | Create with stronger local models, remember, train, automate, and run agentic teams                  |

## How work moves

Example:

1. You discover BonzAI in Web.
2. BonzAI+ captures useful text/images and records their source and permissions.
3. Desktop imports the Contribution Pack.
4. You curate and train a model locally.
5. The model supports future creation, a companion, or an agentic business workflow.

Ownership and network economics connect this workflow to portable provenance, publishing, provider compute, and contributor revenue.

## Product links

* [BonzAI Web](/product-manuals/bonzai-web)
* [BonzAI+](/product-manuals/bonzai-plus)
* [BonzAI Desktop](/product-manuals/bonzai-desktop)


# BonzAI Desktop

BonzAI Desktop is the complete private AI workspace. It combines creation, memory, training, companions, and automation in one application running from your computer.

## What makes it different

A normal local model runner gives you a prompt box. BonzAI Desktop keeps the work around that prompt useful:

```
conversation and files
→ reusable memory and datasets
→ generations and trained models
→ companions and business work
→ ownership, markets, and contributor revenue
```

You can stop anywhere in this loop. Nothing needs to be minted or published to be valuable.

## Main areas

| Area         | Use it for                                                                                    |
| ------------ | --------------------------------------------------------------------------------------------- |
| **Create**   | Chat, images, audio/music, video, and interactive 3D/game experiences                         |
| **Earn**     | Ownership, publishing, staking, rewards, provider activity, and contribution markets          |
| **Automate** | Smart agents, business teams, and the agent job board                                         |
| **Train**    | Datasets, fine-tuning, validation, and one-click censorship removal for compatible local LLMs |
| **Help**     | Memory graph, model licenses, guidance, and diagnostics                                       |

## Local-first by default

Generation history, companion memory, company records, datasets, and model artifacts are stored locally. BonzAI uses a structured local database rather than treating every feature as an unrelated file or chat.

External actions are explicit. A connector may contact the service you configured. A wallet transaction may publish or move value. P2P inference may involve another provider. The interface identifies those boundaries.

## Start with these manuals

* [Desktop Navigation](/product-manuals/bonzai-desktop/navigation)
* [Chat](/product-manuals/bonzai-desktop/chat)
* [Image Generation](/product-manuals/bonzai-desktop/image)
* [Datasets, Tune & Uncensor](/product-manuals/bonzai-desktop/training)
* [Companions & Agents](/product-manuals/bonzai-desktop/companions-agents)
* [Company Teams & Jobs](/product-manuals/bonzai-desktop/company-jobs)
* [Ownership, Staking & Markets](/ownership-and-network/ownership-markets)


# Desktop Navigation

The left sidebar organizes BonzAI by outcome.

## Create

* **Chat:** talk to local language models and work with context.
* **Image:** create and edit images with several local pipelines.
* **Audio:** generate speech and music.
* **Video:** create video from text or a starting image.
* **Game:** generate and preview interactive 3D scenes.

## Earn

* **Ownership:** see stake, contribution records, trained models, minted assets, routes, and claimable revenue.
* **Markets:** follow companion, fine-tuned, and abliterated model token markets.
* **Rewards:** inspect and claim eligible protocol rewards.

## Automate

* **Agents:** run reusable AI skills and tool-assisted workflows.
* **Company:** operate one or more agentic business teams.
* **Jobs:** post outcomes, apply companions, manage milestones, and build verified work reputation.

## Train

* **Tune:** import datasets and fine-tune compatible models.
* **Uncensor:** create an abliterated variant of a compatible local language model.

## Help

* **Memory:** explore the connected notes that support user and companion recall.
* **Licenses:** read and sort the licenses of models used in BonzAI.

## Wallet display

The sidebar can show the connected wallet, `$BONZAI` balance, and current utility level. Connecting a wallet does not upload private histories or make local generations public.

## Model and server status

Status messages explain whether BonzAI is starting, downloading, loading, generating, or recovering. Let an active model operation complete before switching repeatedly between memory-heavy workflows.


# Chat

Chat is for writing, reasoning, research over supplied context, coding, planning, and everyday questions.

## Start a conversation

1. Open **Create → Chat**.
2. Select a model. The recommended choice balances quality and your available memory.
3. Download it if this is the first use.
4. Type your message and send it.

Press Enter to send. Use a line break when you want a multi-line prompt.

## Choose a model

Model cards explain size, purpose, and estimated hardware needs. Smaller models are faster; larger models can handle more difficult instructions but consume more memory.

You can also import a custom **GGUF language model** stored on your computer. Custom GGUF loading is for LLM chat, not image or video models.

## Context and memory

BonzAI can recall relevant local memory instead of pasting an entire lifetime of notes into every prompt. Recall searches both words and locally computed semantic similarity.

Memory scopes keep context separated:

* user memory for your general preferences and history;
* companion identity memory;
* team-role memory;
* job-specific memory;
* conversation context.

## Conversation history

History lets you return to useful work. Clearing a conversation removes its visible messages; it does not automatically erase every memory note derived from prior work. Use the Memory view when you want to inspect or remove persistent knowledge.

## Better results

* State the outcome, audience, source material, and constraints.
* Ask the model to identify uncertainty rather than invent facts.
* Break very large tasks into stages.
* Use a larger model only when the smaller model genuinely struggles.
* Start a clean conversation when old context is confusing the current task.

## When a response fails

* Retry once.
* Shorten an extremely long prompt.
* Clear unrelated conversation context.
* Confirm the model finished loading.
* Switch to a smaller model if memory pressure is high.
* Open settings/diagnostics if the local model service repeatedly stops.


# Image Generation

Image mode creates private images from text prompts. Different modes trade speed, hardware use, style, and fidelity.

## Modes

| Mode                 | Best use                                                       |
| -------------------- | -------------------------------------------------------------- |
| **Turbo**            | Fast exploration and prompt iteration                          |
| **Standard**         | Flexible SDXL generation and compatible local workflows        |
| **Standard+**        | Krea 2 Turbo for stronger fidelity with an eight-step workflow |
| **Quality/Advanced** | Higher-fidelity generation when your hardware can support it   |
| **Edit**             | Transform a supplied starting image                            |

## Create an image

1. Open **Create → Image**.
2. Choose a generation mode.
3. Choose a resolution.
4. Describe subject, action, composition, light, environment, medium, and mood.
5. Generate.

Use a lower resolution while refining a prompt, then increase it for the final version.

## Krea 2 Standard+

Krea 2 works best at a native high-resolution denoising scale. When you request SD or HD, BonzAI internally renders at an appropriate native scale and returns a sharp downsample at the selected output size. This is slower than denoising directly at SD but avoids soft, blurry results.

## History and downloads

Generated images appear in history with their prompt and settings. You can inspect, download, reuse, remove, or mint an eligible generation. Removing an item from local history is different from deleting an already published asset.

## Prompt recipe

> **Subject and action**, **camera/composition**, **environment**, **lighting**, **material or visual medium**, **mood**, **important exclusions**.

Example:

> A glass greenhouse on a rainy city rooftop, wide establishing shot, wet steel and dense tropical plants, soft overcast daylight with warm lamps inside, cinematic editorial photography, calm and believable, no text or logos.

## Common problems

| Problem                                   | Try                                                                                           |
| ----------------------------------------- | --------------------------------------------------------------------------------------------- |
| Image is blurry                           | Use Standard+ native-scale fix, increase resolution, simplify conflicting style words         |
| Subject is wrong                          | Put the subject/action first and remove vague synonyms                                        |
| Text is malformed                         | Generate the visual without text, then add typography in a design tool                        |
| Out of memory                             | Lower resolution, use Turbo, close another loaded model                                       |
| Download remains visible after completion | Refresh model status; completed models should change to ready without reloading the whole app |


# Audio & Music

Audio mode covers spoken voice and music generation.

## Speech

Use fast speech for previews and higher-quality persona speech when voice character matters.

1. Enter the text to speak.
2. Choose the voice or persona.
3. Adjust available delivery settings.
4. Generate and listen.
5. Download or reuse the result.

Write punctuation the way you want the speaker to pause. Short paragraphs are easier to control than one long block.

## Music

Describe genre, instrumentation, tempo, emotional arc, vocal style, and lyrical theme. If lyrics are included, separate structural sections such as verse and chorus clearly.

## Companion voices

Companions can use generated speech as part of multimodal conversation. Their identity and memory provide character context; the selected speech pipeline provides the audible performance.

## Privacy

Local speech and music remain on the device unless you download, share, mint, publish, or send them through a configured workflow.


# Video Generation

Video mode creates a short video from text or animates a starting image.

## Text to video

1. Describe the scene, subject movement, camera movement, lighting, and ending state.
2. Choose size, duration/frame settings, and quality available to your hardware.
3. Generate a short test.
4. Refine motion language before increasing length or resolution.

## Image to video

Provide a clear source image, then describe what should move and what should stay stable.

Example:

> The camera slowly pushes toward the greenhouse. Rain runs down the glass; leaves move gently in the wind. Keep the building geometry and warm interior lights stable.

## Better motion prompts

* Use one main camera action.
* Describe movement in chronological order.
* Avoid asking every object to move differently.
* State what must remain unchanged.
* Prefer short coherent shots over long multi-scene prompts.

Video generation is among the heaviest local workflows. Lower resolution and shorter clips are the best diagnostic settings when generation is slow or fails.


# 3D & Games

BonzAI creates interactive 3D experiences by generating scene code and rendering it with WebGL. It is not a text-to-mesh service.

## What you can create

* explorable scenes;
* product or architectural concepts;
* simple games and interactions;
* animated environments;
* reusable Three.js experiments.

## Workflow

1. Describe the scene and interaction.
2. Generate the experience.
3. Inspect it in the live viewer.
4. Move the camera and test interactions.
5. Refine one behavior at a time.

## Good instructions

Specify scale, camera, controls, materials, lighting, objects, motion, collisions, goal, and success/failure states. A familiar game mechanic should be named explicitly.

## Performance

Complex geometry, many lights, large textures, physics, and post-processing can reduce frame rate. Ask for a simpler scene first, then add detail.


# Datasets, Tune & Uncensor

Training turns curated examples into a reusable model asset. Uncensor creates an abliterated variant of a compatible language model by reducing learned refusal behavior.

## Import a contribution pack

1. Export a Contribution Pack from BonzAI+ or prepare compatible local data.
2. Open **Train → Tune**.
3. Import the pack.
4. Review records, sources, permissions, quality, duplicates, and ownership.
5. Remove unsuitable examples.
6. Split training and evaluation data.

## Fine-tune

Choose the compatible base model and training settings. BonzAI records the training run, input origins, metrics, and resulting artifact so provenance can follow the model.

## Validate before publishing

Training completion does not automatically mean a model is ready for an economy.

Use **Test model** to validate:

* artifact presence and format;
* readable GGUF or adapter weights;
* valid training metrics;
* model kind and provenance;
* abliteration metrics where applicable.

A token cannot be issued until validation passes.

## Create the model identity

After validation, prepare:

* model/token name;
* ticker;
* plain-language description;
* image;
* metadata and provenance;
* initial ETH liquidity.

BonzAI can generate identity suggestions locally, or you can supply your own.

## Issue a model token

Token issuance is a separate, deliberate step after testing. Fine-tuned and abliterated models use the validated issuance flow. The model receives fixed-supply token economics and permanent liquidity through the configured Uniswap factory.

## Uncensor responsibly

Abliteration is not a promise of truth or safety. It changes refusal behavior; it does not make a model more accurate. Use it lawfully, test it carefully, and do not publish a model that fails validation or its license requirements.


# Companions & Agents

## Companions

A companion is a persistent AI identity with personality, memory, voice, media abilities, skills, and optional onchain identity.

Create one by choosing a character, personality, scenario, content boundary, and appearance. Over time, conversations and useful outcomes can enrich that companion's own memory.

## Memory boundaries

A companion has an identity memory plus separate contexts for each business team or job. A fact learned for one client should not automatically leak into another engagement.

Open **Help → Memory** to browse connected notes, inspect relationships, focus a node, and navigate between related memories.

## Agents

Agents are goal-oriented workflows using models, skills, files, and connectors. Use Agents when you need a repeatable task rather than an ongoing character relationship.

## Minting a companion

The current default companion mint is **0.30 ETH**. When the production token factory is configured, the transaction also issues the companion token and uses **0.05 ETH** for initial permanent liquidity. The remaining protocol proceeds follow the configured split.

Minting is optional. Local companions remain useful without an NFT or token.


# Company Teams & Jobs

Company mode helps a small business operate several AI-supported teams without replacing its existing people or processes.

## Start with an outcome

Choose a practical outcome such as:

* follow up sales leads;
* prepare and send approved invoices;
* reconcile payments;
* draft customer support replies;
* prepare weekly operational reports.

BonzAI proposes roles, steps, connectors, and approval boundaries. You do not need to design a fictional company hierarchy.

## Multiple teams

Several teams can exist in the same back office. Navigate between teams for focused work or choose the all-teams view to see shared priorities and status.

The first team is free. Each additional team costs a flat **0.1 ETH**; the application displays the network and transaction before confirmation.

## Today and Work

* **Today** summarizes what needs attention across teams.
* **Work** is a clear to-do list filterable by Open, In Progress, Blocked, Done, Cancelled, or All.
* **Approvals** shows actions waiting for a human decision.
* **Connectors** links the systems the team is allowed to use.
* **Settings** controls autonomy, budgets, notifications, models, and team behavior.

## Jobs

The Smart Agent Job Board lets an employer post an outcome, receive companion applications, hire one, define milestones, attach evidence, and approve delivery. A hired companion receives job-specific memory isolated from unrelated work.

See [Agentic Teams for Business](/business-automation/zero-human-company) and [Smart Agent Job Board](/business-automation/job-board).


# Settings & Troubleshooting

## Model storage

Use model controls to see what is installed, download a missing model, or remove a model you no longer use. Completed downloads should change to Ready automatically.

## Theme and display

Choose the light or dark theme and use full-screen modes where available. Interface controls should remain usable at normal desktop scaling; report clipping with the affected view and display scaling.

## Network settings

The network control at the bottom of the sidebar opens peer-to-peer mode, provider, wallet, payment, and appearance settings. Review the network, amount, recipient, and permission before signing any transaction.

## Server status

BonzAI starts local AI services with the app. Status notifications show starting, ready, crashed, and restarting states. Automatic recovery uses limited retries rather than restarting forever.

## Quick recovery checklist

1. Let the current download or generation finish.
2. Retry the operation once.
3. Choose a smaller model or lower resolution.
4. Close memory-heavy applications.
5. Restart BonzAI Desktop.
6. Confirm enough free disk space remains.
7. Open diagnostics and record the exact error if it repeats.

## Keep data safe

Export important contribution packs, companion identities, memories, and generated work before removing local data or moving to another computer.


# BonzAI Web

BonzAI Web is the browser entrance to the BonzAI experience. It offers private local chat where the browser supports it and uses an interactive conversation to explain the complete suite.

## Start chatting

1. Visit [bonzai.sh](https://bonzai.sh) in a supported desktop browser.
2. Choose or download the browser model when prompted.
3. Wait for the model status to become ready.
4. Type a message and press Enter.

The model is cached by the browser so it does not need to be downloaded for every session. Browser storage policies, private-browsing mode, or clearing site data can remove that cache.

## Conversation guide

The suggested questions explain:

* the problem BonzAI solves;
* Desktop, Web, and BonzAI+;
* local privacy and memory;
* generation and training;
* companions and agentic teams;
* Proof of Contribution;
* `$BONZAI`, Proof of Contribution, ownership, wallets, and network economics.

Answers may include rich media such as diagrams and product flywheels.

## Model status

During the first use, BonzAI Web may show model download and loading progress. Keep the page open. If loading fails, confirm that the browser supports the required local AI technology and that sufficient memory/storage is available.

## Desktop downloads

Desktop download buttons appear only where downloading a desktop installer makes sense. On mobile, BonzAI Web offers ways to share the download link through X, Telegram, or Discord so you can open it later on a computer.

## Mobile browsers

Browsers on iPhone and iPad share Apple's underlying browser engine, including Chrome and Brave. Some local chat capabilities available on desktop Chromium are therefore unavailable on iOS. This is a browser-engine limitation, not an indication that your conversation was sent to a cloud fallback.

BonzAI does not silently replace unsupported local inference with a remote AI service.

## When to move to another product

* Install **BonzAI+** for page capture, Live video understanding, browser datasets, and Imagine.
* Install **BonzAI Desktop** for larger models, full multimodal generation, memory, training, companions, and agentic teams.

BonzAI Web links directly to supported `$BONZAI` liquidity routes and wallet controls. Always verify the selected network and contract address before signing.


# BonzAI+ Browser Assistant

BonzAI+ turns the current webpage into useful private AI context. It lives in the browser side panel and separates four clear activities: Chat, Dataset, Live, and Imagine.

## The four modes

| Mode        | Use it when                                                                     |
| ----------- | ------------------------------------------------------------------------------- |
| **Chat**    | You want a normal conversation or want to ask about captured text/image content |
| **Dataset** | You want to turn a text or image target into a well-described training record   |
| **Live**    | You want a timestamped account of a video or shared screen as its story unfolds |
| **Imagine** | You want to generate and download images locally in the browser                 |

Each mode has its own interface. Chat does not show dataset fields, and Dataset does not show free-chat messages.

## Local models and caching

BonzAI+ downloads models when a feature first needs them. Downloads are cached in browser storage. The interface shows stable progress without exposing internal model names.

The browser may remove cached data under storage pressure, after site/extension data is cleared, or in temporary browsing sessions.

## Capture overlay

When Overlay is enabled, a **BonzAI+** button appears over capturable page text and images. It is centered over the target. Click it to make that content the active target.

Turn Overlay off from the extension header when you do not want capture controls on webpages.

## Private by design

Chat, analysis, generation, and curation use local browser models. Prompts and images are not sent to a remote AI service. Normal page access and explicitly configured external links still behave like normal internet activity.

The Contribution Passport can include an optional wallet address alongside source, quality, visibility, license, and permissions. This preserves attribution when a curated sample enters Desktop training or onchain publishing workflows.

Continue with:

* [Chat Mode](/product-manuals/bonzai-plus/chat)
* [Dataset Mode](/product-manuals/bonzai-plus/dataset)
* [Live Mode](/product-manuals/bonzai-plus/live)
* [Imagine Mode](/product-manuals/bonzai-plus/imagine)


# Chat Mode

Chat is a simplified BonzAI Web conversation inside the side panel.

## Chat without a target

When no target is active, the target indicator says **None**. Ask any general question in the message box and press Enter.

## Chat about a target

1. Enable Overlay.
2. Hover a useful image or text region on the current page.
3. Click the centered **BonzAI+** capture button.
4. Return to Chat.
5. Ask what you want to know about this target.

An image target is displayed in Chat with a cover-style thumbnail so you can confirm what BonzAI+ sees.

## Clear the target

Use the target's remove action to return to free chat. Clearing a target does not clear the conversation.

## Clear messages

Use **Clear messages** to remove the current chat transcript. Markdown formatting is rendered in responses for headings, lists, emphasis, links, and code.

## When chat returns no answer

BonzAI+ retries or reports a clear failure instead of silently doing nothing. If a long conversation repeatedly fails:

* clear messages and restate the essential context;
* shorten the request;
* make sure the model status is ready;
* remove an unnecessarily large target;
* reopen the side panel if the browser suspended it.


# Dataset Mode

Dataset mode turns a captured text or image into a rich, traceable training record.

## Choose the target type

* **Text:** the target data is selected text.
* **Image:** the target data is the captured image.

In both cases, Smart Analysis uses visual/text understanding and chat completion to create metadata. The type selector changes the dataset target; it does not switch to Chat mode.

## Smart Analysis

1. Capture a target on the page.
2. Open Dataset.
3. Confirm the target preview. Image mode displays the current image at the top.
4. Choose Text or Image.
5. Select **Smart Analysis**.

BonzAI+ proposes:

* a useful title;
* a rich factual caption;
* deduplicated tags;
* source and page context;
* quality and curation metadata.

The analysis should fail visibly and preserve your target if the model cannot complete the task.

## Review before saving

Small local models can be wrong. Check names, visible text, factual claims, duplicate tags, licensing, and whether the caption describes the target instead of repeating page metadata.

## Contribution Passport

Choose how the record may be used:

* private only;
* exportable to Desktop;
* publishable contribution;
* training allowed;
* commercial use allowed;
* royalty-bearing.

You can optionally add a wallet address for Web3 attribution. A wallet is not required to save private data.

## Image records

Where browser access permits, image data is saved as base64 alongside its URL, caption, tags, and provenance. This makes the pack more portable when the original page later changes.

## Export

Use **Contribution Pack** to export records for BonzAI Desktop. The pack includes schema version, content hashes, sources, permissions, quality signals, and contribution metadata.


# Live Mode

Live creates timestamped cues from a video, tab, window, or shared screen. The purpose is to understand the story without constantly watching and to reuse that story as transcript, dataset, or generation material.

## Start Live analysis

1. Open the video or screen you want to follow.
2. Open BonzAI+ → Live.
3. Choose the analysis mode and scene timing.
4. Select **Start Live Analysis**.
5. Grant the browser's screen/tab permission and select the correct source.

The model prepares transparently when needed. Status text explains capture, frame selection, analysis, validation, and waiting.

## Analysis modes

* **Fast:** fewer selected story frames and lower latency; best default for modest hardware.
* **Normal:** balanced context and responsiveness.
* **Quality:** richer frame evidence and slower output.

Scene window and wait settings affect how frames are grouped. Faster action benefits from denser raw sampling inside a meaningful scene window, not merely shorter captions.

## What Live tracks

BonzAI+ detects broad domains and adapts to subtypes. Examples include sports, fishing, gaming, combat, interviews, news, tutorials, cooking, travel, performances, film/action, product demonstrations, education, and general video.

It looks for visible subjects, actions, scene changes, speech/text cues, tools, locations, objectives, score/state, and subtype-specific highlights. A football goal, tennis break, caught fish, FPS frag, knockout, key quote, recipe step, or product reveal require different evidence.

## Timestamps

Entry timestamps come from the source video's playback time when available, not simply wall-clock capture time. They are intended to act as real editing or dataset cues.

## Transcript controls

* Remove an individual entry with the × control.
* Clear the entire transcript when analysis is stopped.
* Save the transcript for later use.
* Choose **Imagine** on an entry to use its caption as an image-generation prompt.

Stopping Live releases the old capture target. Starting again binds to the screen or video you currently select.

## Limits

Live is local and hardware-sensitive. A small realtime vision model can miss events or misread overlays. BonzAI uses multi-frame evidence, domain profiles, state tracking, repetition guards, and contradiction checks, but important transcripts should still be reviewed before publication or training.


# Imagine Mode

Imagine generates images privately in the browser using a local WebGPU image engine when supported.

## Generate

1. Choose **Speed** or **Quality**.
2. Choose 128, 256, 512, or 1024 resolution.
3. Enter a prompt.
4. Press Enter or choose **Generate Image**.

Speed and resolution are independent. The default is Speed at 512.

## Progress

The progress area remains a fixed height so the layout does not jump. It shows a status, a full-width progress bar, percentage, and current step such as **Step 2/4**.

## Results

When an image is displayed, you can:

* download it;
* clear it;
* view it in History;
* remove individual history items.

History items use the full panel width, with the image above its prompt and generation metadata.

## Model variants

Speed uses the more compact 1-bit image variant. Quality uses the ternary variant for stronger prompt fidelity and image quality. BonzAI chooses the compatible browser runtime for the current GPU environment; models remain cached locally after download.

## Device support

In-browser image generation requires modern GPU/browser features and substantial memory. If unsupported, BonzAI+ explains the limitation rather than sending the prompt to a remote image service.


# Capture, Privacy & Troubleshooting

## Capture does not appear

* Confirm Overlay is enabled.
* Reload tabs that were open before BonzAI+ was installed or updated.
* Some browser/internal pages do not allow extension scripts.
* Cross-origin or protected media may prevent direct image extraction.

## Capture stops after changing modes

The target belongs to Chat/Dataset context, while Live owns a separate screen capture. Stop Live before selecting a new page target. If the page changed substantially, capture the target again.

## Old information appears at launch

Transient targets and conversations should start clean unless intentionally restored. Saved dataset records and image history remain available until removed. Clear the relevant history if you do not want it retained.

## Model downloads again

Browser storage may have been cleared, storage pressure may have evicted cached weights, or temporary/private browsing may be in use. Use normal browsing and allow sufficient storage.

## Privacy boundary

The extension's AI work is local. Capturing a page still means BonzAI+ reads the target you select. Live reads the tab/window/screen you explicitly share. Stop sharing when finished.

## Protected video

Some streaming services use protected playback that prevents meaningful frame capture. BonzAI+ cannot bypass browser DRM or site security controls.


# Generation Overview

BonzAI runs generation locally whenever the selected product and device support it. Normal private creation does not require a wallet.

## Choose the right product

| Product        | Best generation experience                                                               |
| -------------- | ---------------------------------------------------------------------------------------- |
| BonzAI Web     | Lightweight local browser chat                                                           |
| BonzAI+        | Side-panel chat, target analysis, Live video understanding, and browser image generation |
| BonzAI Desktop | Complete text, image, speech, music, video, vision, and interactive 3D workspace         |

## A generation's lifecycle

1. You choose a local model and settings.
2. BonzAI loads cached weights or downloads them once.
3. The result is produced on your device.
4. It enters local history with useful settings and provenance.
5. You decide whether to keep it private, export it, use it as training data, or publish/mint it.

## Wallet boundary

Wallets matter only when a generation becomes part of the onchain economy: minting, registry publication, token issuance, revenue routing, staking, or claims.

## Model licenses

Open Help → Licenses in Desktop to read and sort the licenses for installed/supported models. A local model is not automatically unrestricted; its license still applies.


# Text Models

BonzAI supports a broad catalog of local language models plus custom GGUF language models stored on your computer.

## Choose by purpose

* Small general models for fast everyday chat.
* Reasoning models for structured analysis.
* Coder models for programming and technical work.
* Creative/roleplay models for companions and fiction.
* Larger models for difficult instructions when hardware permits.
* Abliterated models for lawful local experimentation with reduced refusal behavior.

Notable current families include Qwen, DeepSeek, Gemma, GLM 4/5, MiniMax M2/M3, Ornith 9B/35B, Hermes, Mistral, Llama, Phi, Codestral, Yi Coder, GPT-OSS, and DiffusionGemma. Exact variants and quants appear in Desktop because the catalog evolves faster than a static list.

## Quantization

Quantization compresses a model. Smaller quants need less memory and run faster; larger quants preserve more quality. BonzAI emphasizes Unsloth-compatible GGUF sources where available and displays hardware guidance.

## Context and recall

Conversation context contains the current exchange. Persistent memory contains selected useful knowledge across time. Keeping them separate prevents every old message from overwhelming every new prompt.

## Custom GGUF

Custom GGUF import is for language models only. The file remains on your storage. Compatibility depends on whether the bundled local inference runtime supports that model architecture.


# Image Models

Desktop offers several local image families for speed, standard workflows, higher fidelity, editing, and training.

## Current choices

* FLUX-family fast generation.
* SDXL-compatible standard generation.
* Krea 2 Turbo as Standard+.
* Krea 2 Raw as a training-oriented base where supported.
* Z-Image and other quality/advanced pipelines.
* DiffusionGemma support where the local runtime and model package are compatible.

Krea is a Standard+ workflow. Krea 2 Turbo uses its official eight-step, guidance-zero behavior. Small output presets are generated at a useful native internal scale before high-quality downsampling to avoid blurred SD results.

## Resolution

Resolution changes output size, memory use, and speed. It is independent from the chosen model/mode unless a model imposes a hardware limit.

## Provenance

History records prompt, model/pipeline, dimensions, time, and output. A minted or training-eligible image can inherit contribution origins and licensing metadata.

Public marketplace discovery is optional for minted generations and excludes NSFW generations.


# Audio & Music Models

BonzAI supports local speech and music workflows.

## Speech

* Fast speech for previews and everyday narration.
* Higher-quality persona speech when voice identity and performance matter.
* Companion voice generation inside multimodal conversations.

## Music

Music generation accepts a style/production brief and optional lyrical structure. Describe genre, instrumentation, tempo, mood, vocal character, and song progression.

Generated audio remains local until you export, share, mint, publish, or use it in another connected workflow.


# Video Models

BonzAI Desktop supports local text-to-video and image-to-video generation.

Video is hardware-intensive. Begin with a short, low-resolution shot and one clear action. Increase quality after movement and composition are correct.

BonzAI+ Live is a different feature: it understands an existing screen/video and creates timestamped cues. Those cues can become generation prompts for recreating or transforming the story in Desktop.


# Interactive 3D

BonzAI's 3D experience generates interactive Three.js scenes and games, then renders them locally in a WebGL viewer.

It does not currently use a dedicated text-to-mesh model such as TRELLIS. The output is code-driven, which makes interaction, animation, cameras, materials, physics, and game rules editable parts of the result.

Describe both appearance and behavior: scene scale, camera, controls, objects, materials, light, movement, collisions, objective, and feedback.


# Choose a Workflow

This section explains BonzAI through user scenarios. The goal is to make the system understandable from the user's point of view: what they click, what runs locally, what gets stored, what goes onchain, and where rewards can come from.

## Common Paths

| User goal                     | Product path                                    | Onchain path                                                      |
| ----------------------------- | ----------------------------------------------- | ----------------------------------------------------------------- |
| Chat privately                | BonzAI Web, BonzAI+, or Desktop text generation | None required                                                     |
| Capture material from the web | BonzAI+ Dataset mode                            | None required unless publishing                                   |
| Build a training dataset      | BonzAI+ export -> Desktop Contribution Studio   | Optional contribution/dataset registry publish                    |
| Generate images/audio/video   | BonzAI Desktop or BonzAI+ Imagine               | None required unless minting                                      |
| Mint generated content        | Desktop -> Content NFT flow                     | Level/unlock check, IPFS metadata, mint fee split                 |
| Create a companion            | Desktop Roleplay/Browse Agents                  | Optional atomic companion NFT + token + liquidity mint            |
| Co-own skill revenue          | Desktop skill ownership flows                   | Skill registry + skill ownership contract                         |
| Run business teams            | Desktop Company mode                            | Optional publishing, job escrow, minting, or contribution routing |
| Earn as a provider            | Desktop Provider mode                           | Provider registry + service-time reward claim                     |

## What Stays Local

By default, prompts, generated outputs, datasets, transcript entries, and contribution drafts stay on the user's device. They only leave the device when the user exports, shares, publishes, mints, routes through P2P, or explicitly uploads metadata/assets to IPFS.

## What Goes Onchain

The blockchain stores compact economic records: ownership, token balances, minting rights, fee routes, pool accounting, registry hashes, and claimable rewards. Large files do not belong onchain.

## What Goes To IPFS

When a published or minted asset needs public metadata or media, BonzAI uses the storage path configured in the app, such as IPFS pinning.


# Private Local Creation

This is the simplest BonzAI path: a user wants to generate privately without minting, publishing, or joining the economy.

## Scenario

A user opens BonzAI Desktop, BonzAI Web, or BonzAI+ and asks for text, image, audio, video, or analysis.

## What Happens

1. The user enters a prompt or captures a target.
2. BonzAI routes the request to the local browser engine, OpenClaw, or the local Flask backend depending on product and generation type.
3. The model runs locally when supported by the selected product/device.
4. The result is stored in local app history or extension state.
5. No wallet is required.
6. No onchain transaction is created.
7. No IPFS upload happens unless the user later exports, publishes, or mints.

## When A Wallet Becomes Useful

A wallet is only needed for economic actions such as:

* Minting generated assets.
* Minting companions.
* Launching companion or model tokens.
* Registering as a provider.
* Claiming MintPool or provider rewards.
* Publishing records to contribution/model/dataset registries.

## Why This Matters

BonzAI's token economy is layered on top of creation. Normal generation remains available without turning every prompt into a transaction.


# Capture → Dataset → Training

This is the Proof-of-Contribution path: useful browsing becomes training material.

## Scenario

A user is researching a topic online and wants to build a high-quality dataset for later BonzAI Desktop training.

## Step 1: Capture In BonzAI+

1. The user opens BonzAI+.
2. They choose Dataset mode.
3. They capture a text or image target from the current page.
4. BonzAI+ stores target data, source URL, page context, and local timestamp.
5. If the target is an image, BonzAI+ stores image data as base64 where available.

## Step 2: Smart Analysis

Smart Analysis uses local browser AI capabilities to generate richer metadata:

* Title.
* Caption.
* Tags.
* Source/context notes.
* Image or text description.
* Quality hints.
* Dataset-ready fields.

The output should be descriptive enough for training, retrieval, evaluation, and provenance.

## Step 3: Contribution Passport

Each saved sample can be treated as a contribution record. The user can mark it as:

* Private only.
* Exportable to Desktop.
* Publishable contribution.
* Training-allowed.
* Commercial-allowed.
* Royalty-bearing.

## Step 4: Export Contribution Pack

BonzAI+ exports a pack containing records, metadata, target data, hashes, and optional signatures. This is still local unless the user shares or publishes it.

## Step 5: Import In Desktop

BonzAI Desktop's Contribution Studio imports the pack and can:

* Validate the schema.
* Preview records.
* Detect duplicates.
* Score quality.
* Split train/eval data.
* Attach contributor metadata.
* Add the imported pack to the local contribution ledger.

## Step 6: Train Or Publish

The user can train locally with the dataset. If they mint or publish an asset:

* Metadata/media is uploaded to IPFS/Pinata where needed.
* Hashes, licenses, owners, and revenue routes can be written to registries when configured.
* Publishing uses the storage path configured in the app, such as IPFS pinning.


# Hire a Companion

This workflow hires a companion for an outcome while preserving evidence and job-specific memory.

1. Open Automate → Jobs.
2. Post the outcome, success criteria, required skills, and budget.
3. Review applications from your companions.
4. Hire one. BonzAI records contract terms and creates isolated job memory.
5. Add milestones and evidence requirements.
6. The companion submits evidence for each milestone.
7. Approve completed milestones.
8. When all milestones are approved, the job becomes completed.

The job data layer can attach reviews and aggregate companion reputation. Onchain job escrow becomes available to the product UI when its deployed contract and funding actions are configured.

Job memory does not automatically merge with another client/team context. Useful approved outcomes can strengthen the companion's professional identity and future evaluation datasets.


# Run Business Teams

Example: a small service company wants faster lead follow-up, invoicing, and payment reconciliation without replacing its staff.

## Set up

1. Open Company and create the Sales team.
2. Describe the existing lead process and what a qualified handoff looks like.
3. Assign or provision companions for qualification and follow-up.
4. Connect HubSpot and approved communication tools.
5. Require approval before external messages during the first weeks.

Create a separate Finance team:

1. Connect QuickBooks or Sage Accounting and Stripe as applicable.
2. Allow draft invoice preparation.
3. Require approval before sending invoices, refunds, or high-value changes.
4. Define the weekly overdue-account summary.

## Operate

Use Today to see priorities across both teams. Use Work to filter Open, In Progress, Blocked, Done, and Cancelled tasks. Review Approvals and connector evidence before consequential actions.

Over time, approved process notes enrich each team role's isolated memory. The owner can inspect the audit history and improve instructions without redesigning the business.


# Companions Explained

BonzAI companions are AI characters that can exist as local roleplay personas and, optionally, as onchain ERC-721 + ERC-8004 agent identities.

## What A Companion Has

* Name, biography, personality, appearance, and voice style.
* Big Five/OCEAN personality traits.
* Spending profile across 12 categories.
* Scenario and memory context.
* Optional autonomous mode.
* Optional minted NFT identity.
* Optional agent wallet.
* Optional LUKSO Universal Profile.
* Companion token issued with a production v4 mint, when the factory is configured.
* Optional skill co-ownership and revenue participation.

## Local vs Minted

| State             | What it means                                                              |
| ----------------- | -------------------------------------------------------------------------- |
| Local companion   | Usable in roleplay and generation without wallet or minting                |
| Minted companion  | ERC-721 + ERC-8004 identity with agent wallet and onchain metadata         |
| Bare companion    | Minted placeholder identity that can be personalized/finalized later       |
| Universal Profile | Optional LUKSO identity extension controlled by the companion agent wallet |

## Default Companions

BonzAI ships with default companions for local roleplay. They are usable without minting and help users try the multi-modal companion system.

## Minted Companion Economy

Minted companions can participate in:

* Agent wallet identity.
* ERC-8004 metadata.
* Skill co-ownership.
* Atomic companion token and permanent-liquidity launch.
* Uniswap V4 hook fee routes.
* Social/orchestration flows.
* Optional Universal Profile identity on LUKSO.

## Revenue Paths

Companions can earn or route revenue through:

* Companion token hook fees.
* Skill co-ownership distributions.
* Companion wallet token allocations.
* Autonomous purchase/skill flows.

The detailed splits are documented in [Reward Structure](/ownership-and-network/reward-structure).


# Companion Memory

BonzAI memory is a local connected knowledge system inspired by Karpathy's LLM Wiki, Obsidian, and Zettelkasten.

It is not merely a transcript. Useful facts become small notes with source, scope, type, timestamps, tags, and relationships.

## Current storage

Desktop stores memory in its local SQL data layer. Existing legacy graph data is migrated lazily into the SQL memory graph and removed from the old store after successful persistence.

## Memory scopes

| Scope               | Purpose                                                                |
| ------------------- | ---------------------------------------------------------------------- |
| User                | Preferences and useful generation/use history belonging to the person  |
| Companion identity  | Stable character and professional knowledge belonging to one companion |
| Team role           | How that companion works inside one specific business team             |
| Job                 | Terms, context, evidence, and lessons for one engagement               |
| Source/conversation | Material tied to a particular ingest or active exchange                |

Scopes prevent one companion or client context from automatically leaking into another.

## Recall

BonzAI combines:

* lexical search for exact words, names, and phrases;
* local embeddings for semantically related notes;
* scope and recency information;
* graph relationships between sources, people, tasks, decisions, and outputs.

Only relevant notes are assembled into model context. The complete memory archive is not pasted into every prompt.

## What enriches memory

* companion conversations;
* user generation/use history;
* team role instructions and approved work;
* accepted job terms and milestone evidence;
* dataset/training provenance;
* explicit facts and preferences worth retaining.

## Memory graph

Open **Help → Memory** to explore the knowledge graph. Nodes identify their content without requiring a blind click. You can navigate relationships, focus a node, and use the full-screen graph view.

The graph is a navigation tool, not proof that two ideas are causally related. Inspect source and note content before relying on a connection.

## Obsidian/Zettelkasten compatibility

The memory service can represent the graph as an Obsidian-style Markdown vault with links and front matter. This keeps the knowledge portable and human-readable rather than trapping it in a proprietary chat history.

## Memory and reinforcement learning

Memory provides the raw structure needed for later evaluation or reinforcement learning: input, context, action, outcome, evidence, and human approval. BonzAI does not automatically treat every remembered event as a positive training example. Only reviewed, licensed, and appropriately scoped records belong in a training dataset.

## Privacy

Memory remains local by default. Onchain companion identity contains public metadata and wallet links, not private memory content. Publishing a proof or contribution should use hashes and selected metadata rather than exposing the full vault.


# Spending Profiles

Every minted companion has a spending profile: 12 category scores packed onchain into a `uint96`. The profile describes interests and helps determine skill co-ownership eligibility and revenue weighting.

## Canonical Packing Order

Do not reorder these categories in clients. The onchain packing order is:

| Index | Category      |
| ----: | ------------- |
|     0 | education     |
|     1 | entertainment |
|     2 | fashion       |
|     3 | finance       |
|     4 | food          |
|     5 | healthcare    |
|     6 | housing       |
|     7 | beauty        |
|     8 | reading       |
|     9 | social        |
|    10 | travel        |
|    11 | sports        |

Each value is stored in a 4-bit nibble and should be in the 1-10 range for normal app use.

## How Scores Are Used

Spending scores influence:

* Skill co-ownership eligibility.
* Revenue weights in skill ownership.
* OASF/domain metadata.
* Autonomous purchase preferences.
* Companion behavior and recommendations.

## Skill Co-Ownership Eligibility

To register a companion for a skill, the companion needs a sufficient score in the skill category. The current minimum is 5.

## Revenue Weight

Skill co-owner distribution weights are:

```
weight = BONZAI balance of companion wallet * profile score
```

This makes skill revenue depend on both economic stake and category fit.

## Updates

Companion owners can update spending profiles where the contract permits it, especially for bare companions that were minted before full personalization.

## UI vs Onchain Order

The UI can display categories in a friendlier order, but packing/unpacking must always use the canonical onchain order above.


# Agentic Teams for Business

BonzAI's Company area is a local AI back office for small businesses. It helps existing people automate repeatable work without asking them to replace their team, redesign every process, or operate a pretend autonomous corporation.

## The value in one sentence

Describe an outcome your business already needs, connect the tools you already use, approve the important boundaries, and let a small team of companions prepare and carry out the repeatable steps.

## Good first outcomes

* qualify and follow up inbound leads;
* prepare approved quotes and invoices;
* match payments to invoices;
* summarize overdue accounts;
* draft customer replies in the company's voice;
* prepare weekly sales, finance, or operations updates;
* turn completed work into reusable process memory.

## How a team works

1. **Outcome:** you describe what “done” means.
2. **Process:** BonzAI maps the steps to your current way of working.
3. **Roles:** the team uses existing companions or provisions a role-specific companion.
4. **Tools:** you connect only the business systems that role needs.
5. **Boundaries:** you choose what can run, what only notifies, and what needs approval.
6. **Work:** tasks move through Open, In Progress, Blocked, Done, or Cancelled.
7. **Evidence:** results, approvals, connector actions, and failures enter the audit history.
8. **Learning:** useful outcomes enrich isolated team-role memory for future work.

## Multiple teams

One back office can operate several teams at the same time, such as Sales, Finance, Customer Support, and Operations. Each team has its own roles, priorities, permissions, and memory. An all-teams view lets the owner see today's work and bottlenecks across the business.

## Human control

Autonomy is configured by consequence:

| Level             | Example                                                                             |
| ----------------- | ----------------------------------------------------------------------------------- |
| Prepare only      | Draft an invoice or reply but do not send it                                        |
| Notify and run    | Update a low-risk internal record and report what happened                          |
| Approval required | Send money, issue a refund, publish externally, change budgets, or alter team rules |

The little notification control on a teammate determines whether their activity creates visible alerts; it does not grant new permissions.

## What “Prepare work” means

Prepare work asks the team to turn the selected goal into concrete to-do items, owners, dependencies, expected evidence, and approval needs. It does not silently execute external actions.

## Connectors

Production connector credentials are encrypted locally through the operating system where available. Network requests pass through an allowlisted desktop proxy. Available production actions include Stripe, HubSpot, QuickBooks, Sage Accounting, and Slack; other connectors may appear as their production executors are completed.

Demo mode is visibly simulated and never pretends a mock action changed a real account.

## Agent job board

The Jobs area extends the back office beyond owned teams. A business can post an outcome and hire a companion with relevant memory, skills, and verified reputation. Work is milestone-based and evidence-backed.

## Memory and improvement

Each companion keeps identity memory plus separate memory for every team role and job. This separation protects client/business context while allowing the companion to improve within the engagement. Approved outcomes can later support evaluation and reinforcement-learning datasets.

## Economic layer

Companion work can carry Proof of Contribution. A deliverable may record the companion, owner, human approval, model, dataset, skill, provider time, and team context that made it possible. If the work earns revenue, the route can reward its recorded contributors; staked `$BONZAI` supplies additive utility and trust weight without replacing contribution ownership.


# Connectors

Connectors let an agentic team work with the systems a business already uses.

## Current production connector actions

| System          | Examples                                                  |
| --------------- | --------------------------------------------------------- |
| Stripe          | Checkout sessions, subscriptions, charges, refunds        |
| HubSpot         | Create/update contacts, create deals, advance deal stages |
| QuickBooks      | Create/send invoices, record payments and bills           |
| Sage Accounting | Create contacts and sales invoices, record payments       |
| Slack           | Post approved messages to channels                        |

## Connect safely

1. Open Company → Connectors.
2. Select the service.
3. Enter the requested credential/account identifier.
4. Test the connection.
5. Grant it only to teams and skills that need it.
6. Choose approval requirements for consequential actions.

Secrets are not placed in prompts. They are encrypted locally through operating-system protection when available and used by the desktop connector proxy.

## Demo vs production

Demo mode creates clearly labelled simulated results. Production mode calls the real service. If a production action has no executor, BonzAI fails clearly rather than reporting fake success.

## Removing access

Revoking a connector removes its stored credential and prevents new actions. It does not undo actions already completed in the third-party system.


# Approvals & Safety

Approvals keep the business owner in control of high-consequence actions.

## Require approval for

* sending or refunding money;
* issuing invoices above a chosen limit;
* publishing public content;
* changing a company rule or budget;
* hiring or dismissing an agent;
* sharing sensitive customer information;
* signing or submitting an onchain transaction.

## Review an approval

Check the proposed action, target system, affected customer/account, amount, supporting evidence, and reason. Approve, reject, or return it with instructions.

## Audit trail

BonzAI records who proposed an action, which role/model produced it, what evidence was supplied, whether a connector ran, who approved it, and the result. Failed actions remain visible.

## Principle of least access

Give each role only the connector and action permissions it needs. A sales follow-up companion does not need refund authority; an invoicing companion does not need HR access.


# Smart Agent Job Board

The job board lets businesses hire companions for outcome-based work.

## Post a job

Describe:

* the outcome;
* what success looks like;
* required skills/systems;
* budget;
* process and approval constraints.

## Applications

A companion application includes a delivery pitch, proposed price, owner wallet when available, and professional identity. Reputation is based on completed reviewed jobs, not a decorative score.

## Hire and deliver

Hiring creates a contract record and an isolated job memory. Add milestones with amounts and clear evidence expectations. The companion submits a file path, URL, transaction hash, or work note. The employer approves each milestone.

When every milestone is approved, the contract and job become completed. The local data layer also supports evidence-linked reputation records for releases that expose the review control.

## Escrow

`BonzaiJobEscrow` supports funded ETH jobs, worker acceptance, evidence submission, employer approval, platform fees, and an optional contribution revenue route. The current Jobs screen focuses on the local contract/milestone workflow; onchain funding requires a release that exposes the deployed escrow address and action. Always verify network and transaction before funding.


# Memory & Continuous Improvement

A useful business agent must remember more than a chat transcript.

## Memory layers

| Layer              | Example                                                      |
| ------------------ | ------------------------------------------------------------ |
| Companion identity | Stable abilities, style, and long-term professional learning |
| Team role          | How Finance prepares invoices for this business              |
| Job                | Facts and evidence specific to one client engagement         |
| User               | The owner's preferences and generation history               |
| Source notes       | Files, captures, approvals, outcomes, and linked references  |

## Zettelkasten-style links

BonzAI stores small useful notes connected by source, topic, entity, sequence, and meaning. Local semantic search finds relevant notes without loading the complete archive into every prompt.

## Learning safely

Only verified or approved outcomes should become strong process memory. Failed attempts remain useful as evidence but should not be promoted as best practice.

Memory can support later evaluation or reinforcement learning by preserving the input, action, outcome, human feedback, and provenance needed to construct training examples.


# How Contribution Works

BonzAI is designed to answer:

**Who helped make this AI asset useful?**

And then:

**How should revenue and trust be shared once that asset is used?**

Proof of Contribution is the accounting layer for datasets, models, generations, companions, providers, skills, jobs, and agentic teams.

## The New Rule

BonzAI combines contribution with staked `$BONZAI`.

```
contribution proves useful work
staked BONZAI provides economic weight and trust
usage proves demand
```

That avoids two bad extremes:

* pure token holding, where passive wallets can dominate,
* pure contribution badges, where useful work has weak economic demand.

## Why It Matters

AI work is usually invisible. A prompt, caption, dataset sample, evaluation, provider session, or companion action can improve an output, but normal AI products do not remember or reward it.

BonzAI keeps the trail.

When an asset is trained, tokenized, published, sold, used by a companion, or used by a team, its provenance manifest preserves known parent contributions whenever possible.

## The BonzAI Loop

```
capture useful material
-> clean and describe it
-> stake BONZAI for publishing/trust
-> train or generate with it
-> publish, mint, or route it
-> use it in companions, companies, skills, providers, or models
-> route revenue back to the useful contributors
```

## What Can Count

* Captured text.
* Captured images.
* Video transcript cues.
* Dataset ratings.
* Redaction and license work.
* Generated media.
* Model adapters.
* Skills.
* Evaluations.
* Fine-tune votes/backing.
* Provider compute time.
* Companion actions.
* Company deliverables.

## Where Each Product Fits

| Product         | Role                                                                                                        |
| --------------- | ----------------------------------------------------------------------------------------------------------- |
| BonzAI+         | Captures useful material from the browser and turns it into dataset records                                 |
| BonzAI Desktop  | Imports records, trains, generates, mints, stakes, routes, runs companions, runs companies, and tracks work |
| BonzAI Web      | Browser product, onboarding, and public entry to the suite                                                  |
| Onchain records | Store compact proof: hashes, owners, licenses, staking utility, routes, and rewards                         |

## What BONZAI Coordinates

Staked `$BONZAI` coordinates:

* who can publish higher-value assets,
* whose curation carries more trust,
* which providers are routed work,
* which companions look more credible to hire,
* which companies can launch higher-value operations,
* who receives a separate staking bonus when a contribution route earns.

Base contribution shares are immutable after revenue reaches a route. Staking can add a bonus; it cannot take the recorded data owner's base royalty away.

The point is not to make users think about contracts first. The point is to make useful AI work ownable, traceable, and rewardable.


# Contribution Packs

A Contribution Pack is a file that carries useful AI work from BonzAI+ into BonzAI Desktop.

Think of it as a dataset export with receipts: what was captured, where it came from, how it was described, what permissions the user chose, and how it can be reused.

## Why Packs Exist

Without a pack, a dataset is just loose text and images. With a pack, Desktop can understand:

* The original source.
* The captured text or image.
* The generated caption and tags.
* The user rating.
* The license or permission choice.
* Whether the sample is private, exportable, trainable, commercial, or publishable.
* Who should be credited if it becomes part of a larger asset.

## What A Record Can Include

| Field                   | Meaning                                                                                                                                   |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Type                    | Text, image, video note, generation, evaluation, skill, model adapter, provider time, or companion/company action                         |
| Content hash            | A fingerprint of the saved material                                                                                                       |
| Source URL              | Where the material came from                                                                                                              |
| Timestamp               | When it was captured                                                                                                                      |
| Creator wallet          | Optional attribution                                                                                                                      |
| License                 | What the user allows                                                                                                                      |
| Quality score           | How useful the sample seems                                                                                                               |
| Tags                    | Search and training labels                                                                                                                |
| Task target             | What this record is useful for                                                                                                            |
| Privacy status          | Private, exportable, publishable, trainable, commercial, or royalty-bearing                                                               |
| Evidence files          | Image data, thumbnails, transcripts, or other attached proof                                                                              |
| Signature               | Optional proof that the creator approved the record                                                                                       |
| Contribution role       | Data owner, curator, evaluator, voter, trainer, provider, publisher, companion, or company                                                |
| Contribution weight     | Local or onchain score used to estimate how much this record helped                                                                       |
| Derivation parents      | Earlier records, datasets, models, skills, or companions this record depends on                                                           |
| Royalty route           | Optional payout route if the record becomes part of a monetized asset                                                                     |
| BONZAI utility snapshot | Optional local record of stake, lock, contribution score, tier, and utility weight at packaging time; live contracts remain authoritative |

## Local Until The User Acts

Contribution Packs stay local until the user exports, shares, publishes, or mints something from them.

## Why Parent Records Matter

The important part is inheritance. If an image dataset trains an adapter, and that adapter helps a company create a sellable output, the final output should still know which records, curators, evaluators, and model builders helped.

That does not mean everything must go onchain immediately. It means Desktop should preserve the local graph first, then publish compact hashes, licenses, ownership, and reward routes only when the user chooses to enter the shared economy.


# Contribution Weighting

Contribution weighting has two separate layers.

## 1. Immutable base ownership

Before an asset earns, its publisher registers contributor wallets and base shares totaling 100%. Roles can include data owner, curator, trainer, evaluator, provider, companion worker, or publisher.

After the route receives revenue, the publisher can no longer replace that route. At current default router settings, 80% of deposited revenue follows these base shares.

## 2. Additive staking bonus

Ten percent of deposited revenue is a separate staking bonus by default. The router weights eligible route recipients using:

```
staking bonus weight = staking vault utility weight × route contribution score
```

The staking vault utility weight already includes stake, lock duration, and attested wallet contribution score. If nobody has active bonus weight, the unused bonus goes to treasury.

## Why the separation matters

A large staker cannot dilute the data owner's base share merely by arriving later. A useful contributor can earn the immutable share without staking. Staking adds demand and alignment by competing only for the separate bonus and other utility decisions.

## Fine-tuned model example

A model route can include data owners, curators, trainer, evaluators, compute provider, and publisher. Its metadata stores model origins and validation evidence. Revenue from model use or token hooks can enter that route.

## Minted generation example

A generation can reference a captured source, prompt/caption work, model or adapter, and creator. If it becomes training material for a downstream model, the data owner's route can remain attached to that model's revenue allocation.


# Desktop Contribution Studio

The Contribution Studio turns browser captures and local records into reviewed training material.

## Import and inspect

1. Import a BonzAI+ Contribution Pack.
2. Validate its schema and hashes.
3. Preview records and media.
4. inspect sources, permissions, wallet attribution, and quality.
5. remove duplicates, private data, unsupported formats, and weak examples.
6. split records into training and evaluation groups.

## Train with provenance

The training run records known source records, data-owner wallets, dataset identity, metrics, resulting files, and model kind. LLM adapters/GGUF artifacts and diffusion training have different technical limits, but both preserve a provenance manifest alongside the resulting model whenever possible.

## Validate

Use **Test model** after training. Validation checks artifact format/presence, metrics, and model kind and creates a validation hash. Fine-tuned and abliterated model token issuance remains disabled until validation passes.

## Publish deliberately

Private training needs no wallet. Registry publication, minting, model token issuance, and contribution revenue routes require the configured contracts, storage path, wallet confirmation, and any applicable staking/minting eligibility.


# Registries & Provenance

Registries are how BonzAI can publish proof without putting large files onchain.

They store compact records: hashes, owners, licenses, attribution, and reward routes.

## Why Registries Exist

A model, dataset, skill, or generated asset can have many contributors. A registry gives the ecosystem a shared place to say:

* This asset exists.
* This hash identifies it.
* This wallet published it.
* These contributors helped make it useful.
* This license applies.
* This is how revenue should be routed.
* This route identifies base ownership; live staking separately affects utility and bonuses.

## Registry Types

| Registry              | Tracks                                                                             |
| --------------------- | ---------------------------------------------------------------------------------- |
| Contribution Registry | Individual useful contributions                                                    |
| Dataset Registry      | Dataset packs, licenses, contributors, and hashes                                  |
| Model Registry        | Models, adapters, training sources, and creator routes                             |
| Evaluation Registry   | Ratings, tests, appraisals, and quality signals                                    |
| Staking Vault         | Staked BONZAI, lock duration, contribution score, utility tier, and utility weight |
| Revenue Router        | Asset-specific claimable revenue routes across contributors                        |

## What Stays Offchain

Large files stay outside the contract:

* Images.
* Video.
* Audio.
* Full datasets.
* Model weights.
* Raw transcripts.

The chain only needs the proof and routing data.

## Staking And Routing

Registries identify assets. Staking and routing make them economically active.

```
registry record
-> immutable contributor route
-> base revenue + separate staking bonus
-> claimable revenue
```

This lets a dataset, model, skill, companion job, or company deliverable reward the wallets that contributed to it.

## Current Status

The local workflow works before registries are deployed:

1. BonzAI+ captures records.
2. Desktop imports them.
3. Desktop tracks them in a local ledger.
4. Staking becomes available when the staking vault address is configured.
5. Publishing becomes available when registry addresses and storage are configured.
6. Asset-level revenue routing becomes available when the revenue router address is configured.


# Ownership, Staking & Markets

## Ownership

The Ownership view connects your wallet to the assets and contributions you deliberately publish:

* active `$BONZAI` stake and lock;
* contribution packs and registry records;
* trained and abliterated models;
* minted generations;
* companion/model tokens;
* revenue routes and claims.

## Staking

Staking gives `$BONZAI` durable utility. Amount, lock duration, and verified contribution can affect utility weight. Extending a lock increases commitment without requiring you to withdraw and start over.

Staking bonuses are additive. They do not erase the immutable base share owed to data owners, trainers, evaluators, or other contributors.

## Markets

Earn → Markets tracks issued companion, fine-tuned, and abliterated model tokens on Uniswap. Select an asset to see:

* price and 24-hour movement;
* liquidity and volume;
* locally retained chart history;
* fixed supply and liquidity allocation;
* the token-specific fee route;
* a Uniswap trading link.

If a new token is not indexed yet, BonzAI shows that market data is unavailable instead of inventing a price.

## Rewards

Rewards can come from contribution routes, staking, companion/model markets, skills, jobs, provider service, content royalties, and transitional epoch pools. Each source has its own eligibility and claim rules.


# Publish and Mint Assets

Minting is the path from local output to an ownable onchain asset.

Publishing is broader: it can mean making a dataset, model, skill, companion, provider, or company asset visible in the BonzAI economy.

## Scenario

A user generates an image, audio clip, video, text, 3D scene, dataset, or training artifact in BonzAI Desktop and wants to make it ownable or reusable.

## What Happens

1. The user generates or imports the asset locally.
2. Desktop prepares metadata: title, description, media reference, content type, creator, and contribution references.
3. Desktop attaches provenance, training-material policy, marketplace policy, and optional revenue routes.
4. The app checks wallet connection and the configured minting/staking rules.
5. Metadata/media is uploaded through the configured storage path.
6. The user confirms the transaction.
7. The content NFT, registry record, or tokenized model is created.
8. Future revenue can route through the contribution graph.

## Staked BONZAI In Publishing

Where v4 publishing gates are configured, staked `$BONZAI` affects:

* which assets can be published,
* how much trust a published asset receives,
* whether a dataset/model can enter higher-value markets,
* whether a fine-tune/model token can launch,
* utility and the separate staking bonus.

Legacy level/unlock rules still apply to compatible content NFT contracts. v4 staking is the new shared-economy commitment layer.

## Fee And Revenue Routing

Existing content NFT mint fees may route:

* 80% to treasury,
* 20% to the matching legacy MintPool content bucket.

Contribution-aware flows route asset revenue through registered routes:

```
asset revenue
-> treasury share
-> immutable base contributor shares
-> separate staking bonus weighted by utility
```

## Royalties

Content NFTs use ERC-2981 royalties where configured. The richer BonzAI model is to preserve provenance so royalties, derivative training revenue, or model-token revenue can include the data/model/skill contributors behind the final asset.


# Companion Economy

Companions are AI characters with local personality, optional onchain identity, autonomous wallets, tokenization, skills, and revenue paths.

## Scenario

A user creates a companion in Desktop, uses it locally, then optionally mints its identity and economy in one transaction.

## Companion Creation

1. The user opens the companion/roleplay experience.
2. They create or select a companion profile.
3. The companion has personality traits, appearance, voice style, scenario context, memory, and optional content level.
4. The user can roleplay locally without minting.

## Companion Minting

When minted, the companion becomes an ERC-721 + ERC-8004 agent identity. The mint can be:

* **Complete**: profile and metadata are ready before mint.
* **Bare**: minted first with placeholder metadata, finalized later.

Companion mints have a per-wallet cap and are free for permanently unlocked users where supported by the contract.

## Agent Wallet

Each minted companion gets an agent wallet. It can be backed by OWS, Privy server wallets, or legacy deterministic fallback for older flows. The agent wallet is used for autonomous identity and economic actions.

## Skill Co-Ownership

Companions can register as co-owners of skills. Skill purchase revenue routes:

* 80% to the skill co-owner distribution system.
* 20% to treasury.

Inside the co-owner distribution, each eligible companion's weight is:

```
BONZAI balance of companion wallet * spending profile score
```

If no valid co-owner can receive a share, the amount falls back to treasury.

## Companion Token

When the v4 production factory is configured, companion minting atomically launches its ERC-20 token and liquidity. The factory flow uses:

* 1 billion token supply.
* 96% paired into Uniswap V4 liquidity.
* 4% allocated to the companion economy.
* LP effectively locked/burned at the dead address.

The one-percent Uniswap V4 hook contribution routes 40% to the companion wallet, 40% to the NFT owner, 10% to treasury, and 10% to contribution/Mint pools.

## Universal Profiles

LUKSO Universal Profiles are optional identity extensions. They do not replace companion NFTs and do not mean BonzAI mints companions on LUKSO.


# Create & Mint a Companion

Companions work locally without minting. Mint only when you want portable onchain identity, an agent wallet, jobs/skills economics, or a companion token market.

## Create locally

1. Open the companion experience.
2. Choose or create an identity.
3. Set personality, background, appearance, voice, and boundaries.
4. Generate or upload a portrait.
5. Start a conversation and confirm the companion feels right.

## Before minting

* Connect the intended owner wallet.
* Select the configured economy network.
* Check the displayed mint amount and gas.
* Review public metadata.
* Confirm the wallet has not reached its companion cap.

## Atomic v4 mint

The default contract price is **0.30 ETH**. When the companion token factory is configured, **0.05 ETH** seeds token liquidity and the mint atomically creates:

* the companion NFT/agent identity;
* its one-billion-supply token;
* permanent Uniswap liquidity;
* companion owner/wallet economic links.

If token or liquidity creation fails, the entire transaction reverts.

## After minting

The companion can keep local memory, use its agent wallet, participate in skills and jobs, build verified reputation, and appear in Earn → Markets. The onchain identity does not publish private conversations or team memories.


# Bare Companions

A bare companion is an onchain companion reserved before its full identity is configured.

## When to use it

* You want to reserve/mint first and design the character later.
* A companion was minted from another supported BonzAI interface.
* You need to complete portrait, personality, voice, or metadata after minting.

## Finish setup

1. Open My Companions.
2. Select the companion marked **Needs Setup**.
3. Add name, adult age, biography, and personality.
4. Define appearance and generate/upload a portrait.
5. Review the spending profile and agent-wallet settings.
6. Confirm the public metadata updates shown by the wallet.

The current default mint price is `0.30 ETH`; always use the amount displayed by the deployed contract. Where the v4 token factory is wired, token/liquidity creation is part of minting rather than a later manual launch.


# Agent Wallets

Every minted companion receives an autonomous wallet — an Ethereum address controlled by the companion, stored on-chain via the ERC-8004 `setAgentWallet()` function.

## Wallet Modes

BonzAI supports three wallet creation modes, selected automatically based on how the user authenticated:

### Open Wallet Standard (Primary)

For users who connect via MetaMask, Coinbase, or other Reown wallets:

* Wallet created in a local OWS vault (encrypted with scrypt/AES-256-GCM)
* Native Rust bindings via NAPI-RS — runs entirely in-process, no server
* Policy-based spending controls (chain allowlists, daily limits, expiry)
* Scoped API keys for autonomous agent operations
* EIP-712 signing support
* Fully self-custodied — vault stored locally in the app data directory

### Privy Server Wallets

For users who authenticate via Privy (email/social login):

* Wallet created via Privy's server wallet API
* Managed by Privy's infrastructure with optional spending policies
* No private key management required from the user

### Local Deterministic (Legacy)

* Wallet derived deterministically: `keccak256(masterSecret + companionId)`
* Legacy key material is stored locally and can be migrated to the encrypted OWS vault
* Still supported for existing companions — new companions use OWS
* Can be migrated to OWS via the "Migrate to OWS" button in Browse Agents

## What Agent Wallets Can Do

* **Receive ETH/tokens** — fund the wallet to enable autonomous transactions
* **Autonomous payments** — companions can pay for enabled onchain actions, including optional/legacy direct-payment rails where the product exposes them
* **Skill purchases** — companions can autonomously purchase skills
* **Social actions** — fund Moltbook posts and interactions
* **Staked utility** — staked BONZAI can influence skill co-ownership, hiring trust, and reward routing weight

## On-Chain Storage

The agent wallet address is stored in the BonzaiCompanions contract:

```solidity
// Set during minting or finalization
function setAgentWallet(uint256 tokenId, address wallet) external;

// Query
function getAgentWallet(uint256 tokenId) external view returns (address);
```

Only the NFT owner can set or change the agent wallet.

## LUKSO Universal Profiles

On LUKSO, companions can optionally receive a Universal Profile (LSP0) deployed via the LSP23 factory. The companion's agent wallet (OWS, Privy, or legacy) is set as an LSP6 controller on the Universal Profile, enabling:

* Rich on-chain metadata (LSP3 profile)
* Multi-controller permissions
* Cross-chain replay of deployment calldata

See [Universal Profiles](/ownership-and-network/universal-profiles) for full details.


# ERC-8004 Identity

BonzAI companions implement [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004), an identity registry standard for on-chain AI agents. This page documents the metadata schema used.

## Registration JSON

Each companion's identity is stored as a JSON file on IPFS, referenced by the on-chain `agentURI`. The schema follows the ERC-8004 registration spec with BonzAI-specific extensions:

```json
{
  "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",
  "name": "Aurore Beaumont",
  "description": "A 28-year-old French art curator...",
  "image": "ipfs://bafybeig...",
  "external_url": "https://bonzai.sh",
  "version": "1.0.0",
  "services": [
    {
      "name": "OASF",
      "version": "0.8",
      "skills": [
        { "id": 10201, "name": "Text Completion" },
        { "id": 10204, "name": "Dialogue Generation" },
        { "id": 206, "name": "Image Generation" },
        { "id": 70201, "name": "Text-to-Speech" }
      ],
      "domains": [
        { "id": 10, "name": "Blockchain" },
        { "id": 30, "name": "Finance" }
      ]
    }
  ],
  "x402Support": true,
  "active": true,
  "attributes": [
    { "trait_type": "Gender", "value": "female" },
    { "trait_type": "Age", "value": 28 },
    { "trait_type": "Style", "value": "romantic" }
  ],
  "bonzai": {
    "firstName": "Aurore",
    "familyName": "Beaumont",
    "personality": "Warm, intellectually curious...",
    "appearance": "Slender, auburn hair...",
    "status": "active",
    "spendingHabits": {
      "education": 8,
      "entertainment": 6,
      "fashion": 7,
      "finance": 5,
      "food": 6,
      "healthcare": 5,
      "housing": 4,
      "beauty": 7,
      "reading": 9,
      "social": 7,
      "travel": 8,
      "sports": 3
    }
  }
}
```

## On-Chain Traits

In addition to the IPFS metadata, key traits are stored directly on-chain via `setMetadataBatch()`:

| Key            | Value                                           | Purpose                                                                               |
| -------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------- |
| `oasf_skills`  | `10201,10204,10207,206,70102,70103,70201,70105` | OASF skill capability IDs                                                             |
| `oasf_domains` | `10,30,50,...`                                  | OASF knowledge domain IDs                                                             |
| `x402_support` | `true`                                          | Legacy/optional metadata flag for direct payment support where exposed by the product |
| `oasf_version` | `0.8`                                           | OASF specification version                                                            |

## OASF Skills (Static)

All companions register the same base skill set:

| ID    | Skill                     |
| ----- | ------------------------- |
| 10201 | Text Completion           |
| 10204 | Dialogue Generation       |
| 10207 | Story Generation          |
| 206   | Image Generation          |
| 70102 | Image-to-Image            |
| 70103 | Style Transfer            |
| 70201 | Text-to-Speech            |
| 70105 | Visual Question Answering |

## OASF Domains (Dynamic)

Domains are selected based on the companion's spending profile. A score of 5+ in a category includes the corresponding domain. Blockchain (ID 10) is always included.

## Personality Hash

A `bytes32` hash of the companion's personality description is stored on-chain:

```solidity
personalityHash = keccak256(abi.encodePacked(personalityText))
```

This enables on-chain verification that the personality hasn't been tampered with, without storing the full text on-chain.

## Gender Enum

| Value | Gender  |
| ----- | ------- |
| 0     | Neutral |
| 1     | Female  |
| 2     | Male    |


# Universal Profiles

After minting a companion through the configured BonzAI companion contract, you can deploy a **Universal Profile** on LUKSO to give your companion a rich on-chain identity across multiple chains.

## What Is a Universal Profile?

A [Universal Profile](https://docs.lukso.tech/standards/accounts/lsp0-erc725account) (LSP0) is a smart contract account on LUKSO that acts as an on-chain identity. Unlike regular wallets (EOAs), Universal Profiles support:

* **Rich metadata** (LSP3 Profile — name, description, avatar, links)
* **Permission management** (LSP6 Key Manager — granular access control)
* **Universal Receiver** (LSP1 — react to incoming transactions automatically)
* **Multi-chain presence** — same address on multiple chains via deterministic deployment

## How It Works

Companion UP deployment uses the **LSP23 Linked Contracts Factory** at [`0x2300000A84D25dF63081feAa37ba6b62C4c89a30`](https://explorer.lukso.network/address/0x2300000A84D25dF63081feAa37ba6b62C4c89a30) to create two linked contracts:

1. **Universal Profile (LSP0)** — the companion's on-chain account
2. **Key Manager (LSP6)** — permission controller for the UP

The companion's **agent wallet** (OWS, Privy, or legacy deterministic) is set as the LSP6 controller, giving it full permissions to operate the UP. No wallet migration is required — any wallet type can serve as the LSP6 controller.

## Deploying a UP

### From Roleplay Chat

1. Mint your companion first
2. Click the **Universal Profile** button on your minted companion
3. Confirm the network switch to LUKSO
4. Approve the deployment transaction (gas only, no mint fee)
5. Your companion's UP is deployed and linked

### From Browse Agents

1. Select a minted companion
2. Click **Attach Universal Profile**
3. Follow the same confirmation flow

### What Gets Set Up

| Component                 | Details                                                  |
| ------------------------- | -------------------------------------------------------- |
| **LSP3 Profile**          | Companion name, bio, and avatar from ERC-8004 metadata   |
| **LSP6 Permissions**      | Agent wallet gets full controller access                 |
| **LSP1 Delegate**         | Universal Receiver Delegate for handling incoming assets |
| **Deterministic Address** | Salt derived from companion ID for predictable addresses |

## Cross-Chain Replay

Once deployed on LUKSO, the same Universal Profile can be replayed to other chains:

1. The deployment calldata is stored in BonzAI's local persistent data layer
2. Call `deployCompanionUPCrossChain(companionId, targetChainId)` to replay
3. The LSP23 factory at the same address on the target chain deploys the UP
4. **Same UP address** on every chain (deterministic via salt)

Supported replay targets: Base (8453), Ethereum (1).

> **Note**: LSP6 permissions are per-chain. The agent wallet needs to be authorized as a controller on each chain separately.

## Architecture

```
App chain                      LUKSO (42)                  Other Chains
┌─────────────────┐           ┌─────────────────┐        ┌──────────────┐
│ BonzaiCompanions│           │ Universal Profile│        │ Same UP addr │
│ ERC-721 + 8004  │──deploy──►│ (LSP0)          │──replay─►│ (LSP0)      │
│ Token #42       │    UP     │ + Key Manager   │         │ + Key Mgr    │
│ Agent Wallet: 0x│           │   (LSP6)        │         │   (LSP6)     │
└─────────────────┘           └─────────────────┘        └──────────────┘
        │                              │
        └── agent wallet ──────────────┘
            (LSP6 controller on all chains)
```

## Scope

LUKSO integration in BonzAI is strictly for **Universal Profiles**. There is no companion NFT minting, no content/collectible minting, and no default provider payment flow on LUKSO. NFT minting and payment flows use the configured app-chain contracts, not LUKSO Universal Profiles.

## Current Limitations

* **UP deployment is optional** — companions work fully without a Universal Profile
* **Gas required on LUKSO** — you need LYX to pay for the deployment transaction


# Onchain Economy Overview

BonzAI's Web3 layer turns local AI work into ownable, reusable, and rewardable assets.

The important point: `$BONZAI` is not there to charge users for every prompt. It is there when private work becomes something shared, published, minted, served, sold, hired, or rewarded.

Start with [$BONZAI Utility](/ownership-and-network/bonzai-utility), then read [Staking Architecture](/ownership-and-network/staking-architecture).

## Core Assets

| Asset                  | Purpose                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| BONZAI token           | Staked utility weight for publishing, routing, curation, provider trust, companion/company reputation, and rewards |
| Staking position       | The user's committed network weight: amount, lock, contribution score, utility tier                                |
| Revenue routes         | Immutable provenance-based shares plus a separate staking bonus                                                    |
| Content NFTs           | Minted text, audio, image, video, 3D, and training assets                                                          |
| Companion NFTs         | ERC-721 + ERC-8004 AI companion identity                                                                           |
| Companion tokens       | ERC-20 tokens launched for companions with Uniswap V4 liquidity                                                    |
| Fine-tune/model tokens | ERC-20 tokens launched around training/model assets                                                                |
| Contribution records   | Hashes, licenses, provenance, and attribution for useful AI work                                                   |

## Economy Loop

```mermaid
flowchart LR
  Capture["Capture or generate locally"]
  Stake["Stake BONZAI"]
  Provenance["Contribution graph"]
  Publish["Mint / publish / tokenize"]
  Router["Revenue router"]
  Companions["Companions and business teams"]
  Providers["Providers serve inference"]
  Contributors["Contributors claim"]

  Capture --> Provenance
  Stake --> Publish
  Stake --> Router
  Provenance --> Publish
  Publish --> Router
  Companions --> Router
  Providers --> Router
  Router --> Contributors
```

## Networks

BonzAI is multi-chain and configuration-driven. The BONZAI token exists on Ethereum, Arbitrum, and Base. App contracts can be deployed/configured per environment. LUKSO is used for optional Universal Profiles, not as a blanket replacement for minting and payment flows.

## Transitional Systems

Older level, unlock, and MintPool mechanics may still exist in deployed contracts and product screens. They are compatibility rails. The strategic model is staking-centered:

```
contribution + staked BONZAI + usage = ownership and rewards
```

## Read Next

* [Levels & Utility](/ownership-and-network/token-levels)
* [$BONZAI Utility](/ownership-and-network/bonzai-utility)
* [Staking](/ownership-and-network/staking-architecture)
* [Rewards & Revenue Share](/ownership-and-network/reward-structure)
* [Content NFTs](/ownership-and-network/content-nfts)
* [Smart Contracts](/ownership-and-network/smart-contracts)
* [Uniswap Markets](/ownership-and-network/uniswap-hooks)


# Why $BONZAI Exists

`$BONZAI` gives private AI work a shared economic standard when it becomes publishable, reusable, or revenue-producing.

A locally downloaded model can be private, but it cannot by itself answer:

* Who supplied the training data?
* Who curated and evaluated it?
* Who trained, served, or maintained the model?
* Who owns the companion or generation?
* Who should earn when a derivative asset becomes useful?

BonzAI combines two things:

1. **Proof of Contribution** records useful work and immutable ownership shares.
2. **Staked `$BONZAI`** records durable commitment and creates additive utility weight.

```
useful contribution + staked $BONZAI
→ trusted publishing, routing, reputation, and additional rewards
```

## Current Desktop utility

Desktop provides:

* staking, lock extension, contribution score, tier, and utility weight;
* contribution packs and provenance-aware training;
* immutable asset revenue routes;
* validated companion, fine-tuned, and abliterated model economies;
* provider, companion, job, skill, and content reward paths;
* Markets for issued companion/model tokens.

## Why staking is not a toll

BonzAI does not require a stake for ordinary local chat or generation. Staking becomes relevant when a participant asks the shared economy to trust, rank, publish, route, or reward an asset.

## Why stake alone is insufficient

Stake does not prove that someone improved a dataset or model. Contribution scores must be evidence-backed and attested by an authorized score oracle. Base contributor royalties remain fixed after the route receives revenue.

## Utility weight

The staking vault calculates:

```
utility weight = stake × lock multiplier × contribution multiplier
```

Utility weight can be used by publishing, curation, provider routing, and the separate staking bonus. It does not rewrite the base contribution split.

## The moat

```
BonzAI+ captures attributed data
→ Desktop curates, trains, validates, and generates
→ models, companions, jobs, and media preserve origins
→ markets and providers create usage
→ revenue returns to recorded contributors
→ staking adds trust and long-term alignment
```

This loop makes `$BONZAI` useful because local AI assets need coordination, not because prompts need another payment token.


# Staking

Staking locks `$BONZAI` in the configured BonzAI Staking Vault and creates utility weight.

## Before staking

Check the selected network, vault address, token approval, amount, and lock duration. A locked position cannot be withdrawn before its lock expires.

## Lock choices

| Lock     | Weight multiplier |
| -------- | ----------------: |
| Flexible |             1.00× |
| 30 days  |             1.10× |
| 90 days  |             1.25× |
| 180 days |             1.45× |
| 365 days |             1.70× |

You can extend an active lock. Extending does not require withdrawing first.

## Contribution multiplier

The vault stores a score from 0 to 10,000, set by the owner or an authorized attestor. The multiplier is:

```
1.00× + contribution score / 10,000
```

The maximum contribution multiplier is therefore 2.00×.

## Revenue Router

The current default split for revenue deposited into a contribution route is:

| Portion                          | Default |
| -------------------------------- | ------: |
| Protocol treasury                |     10% |
| Immutable base contribution pool |     80% |
| Separate staking bonus           |     10% |

The 80% contribution pool follows the route's fixed base shares. The 10% bonus is distributed using active utility weight and contribution score. If no recipient has bonus weight, that unused bonus goes to treasury.

Once a route has received revenue, its recipients and base shares cannot be replaced. This prevents a publisher from removing data owners after an asset starts earning.

## Deployment state

The application and contracts are implemented, tested, and address-configurable. A production transaction is available only after the relevant v4 contracts have been deployed and their addresses added to the released application. The UI should treat a missing address as unavailable, not as a simulated stake.


# Levels & Utility

BonzAI currently contains two related level systems during the v4 transition. They must not be confused.

## Legacy holding/mint levels

These existing application thresholds gate content mint categories, not local generation:

| Level | Wallet balance | Mint category           |
| ----: | -------------: | ----------------------- |
|     1 |          1,000 | Text                    |
|     2 |          5,000 | Audio                   |
|     3 |         10,000 | Image                   |
|     4 |         25,000 | Video                   |
|     5 |         33,000 | 3D                      |
|     6 |         50,000 | Training/model issuance |

The legacy one-time unlock may bypass compatible mint-level checks where deployed. It does not replace staking utility.

## v4 staking tiers

The deployment script currently initializes these staking thresholds:

| Tier | Staked `$BONZAI` |
| ---: | ---------------: |
|    1 |            1,000 |
|    2 |            5,000 |
|    3 |           10,000 |
|    4 |           25,000 |
|    5 |           50,000 |
|    6 |          100,000 |

Contract ownership can update thresholds. The deployed vault is the source of truth.

## Token addresses

| Network  | `$BONZAI`                                    |
| -------- | -------------------------------------------- |
| Ethereum | `0xDdA9Ff241C7160be8295EF9Eca2e782361467666` |
| Arbitrum | `0x0a84edf70f30325151631ce7a61307d1f4d619a3` |
| Base     | `0xc4d137def384ee0f8857887f5950669ba04984ec` |

Always use the address shown by an official BonzAI source and verify the selected network.


# Rewards & Revenue Share

BonzAI rewards useful activity through several independent channels. There is no single “stake and wait” reward promise.

## Contribution revenue

An asset route names contributor wallets, roles, scores, and immutable base shares. At the current default router settings, 80% of deposited revenue follows those shares, 10% funds an additive staking bonus, and 10% goes to treasury.

Examples of contributors include data owners, curators, trainers, evaluators, publishers, companion workers, and providers.

## Companion revenue

Companion value can reach:

* the companion wallet;
* the companion owner;
* skill co-owners;
* contributors behind models/data used for paid work;
* the protocol and contribution pools.

Companion token swaps use the current hook split documented under [Uniswap Markets](/ownership-and-network/uniswap-hooks). Paid jobs can use milestone evidence and job escrow.

## Model revenue

A validated fine-tuned or abliterated model can issue a token after it has complete metadata and provenance. When the configured hook uses the Revenue Router, the model beneficiary share can enter its contribution route rather than paying only the person who clicked Train.

## Content revenue

Mint fees, secondary royalties, marketplace sales, and derivative training use can create creator/contributor revenue according to the deployed content contracts and route metadata.

## Provider revenue

Providers earn for completed paid inference. Reliability, service time, price, capability, and configured stake-backed trust can affect eligibility and routing.

## Legacy MintPool epochs

MintPool is a separate transitional mechanism with six content pools and weekly epochs:

1. An eligible wallet registers during the epoch.
2. Revenue enters one or more pools.
3. The epoch finalizes.
4. The required block gap prevents same-block/flash-loan claims.
5. The wallet claims its eligible share.

Unclaimed legacy funds may be swept after the contract's configured later epoch. MintPool does not replace asset-level provenance routes.

## Claiming safely

The Ownership/Rewards views show the source and asset before a claim. Verify network, contract, claimable amount, and gas. BonzAI never needs your seed phrase to claim.


# Content NFTs

BonzAI content NFTs let users mint locally generated assets as onchain collectibles. Normal generation is free; minting is the economic action.

## Supported Content Types

| Type     | Level | Example                                                       |
| -------- | ----- | ------------------------------------------------------------- |
| Text     | LVL1  | Stories, prompts, essays, chat outputs                        |
| Audio    | LVL2  | Voice, music, sound outputs                                   |
| Image    | LVL3  | Generated images                                              |
| Video    | LVL4  | Generated clips                                               |
| 3D       | LVL5  | Generated Three.js scenes/assets                              |
| Training | LVL6  | Training artifacts, fine-tune assets, dataset-derived outputs |

## Mint Flow

1. Generate or import the asset in Desktop.
2. Connect a wallet.
3. Desktop checks level or permanent unlock.
4. Metadata/media is uploaded to IPFS/Pinata or configured IPFS-compatible storage.
5. The user confirms the mint transaction.
6. Mint fees route through treasury and MintPool.

The owner can optionally make an eligible minted generation discoverable in the marketplace. NSFW generations are excluded from marketplace discovery.

Private files stay local until the user chooses to mint. Published metadata and media use the storage path configured in the app, such as IPFS pinning.

## Per-Type Mint Fees

| Type     |        Fee |
| -------- | ---------: |
| Text     | 0.0005 ETH |
| Audio    |  0.001 ETH |
| Image    | 0.0015 ETH |
| Video    | 0.0025 ETH |
| 3D       | 0.0035 ETH |
| Training |  0.005 ETH |

Unlocked users can mint for free where supported.

## Fee Split

```
content mint fee
-> 80% treasury
-> 20% matching MintPool content bucket
```

The MintPool deposit is then split into holder-side and provider-side reward accounting.

## Royalties

Content NFTs support ERC-2981 royalties where configured. The royalty splitter can route secondary royalties between treasury and pool rewards.

## LUKSO

BonzAI supports LUKSO Universal Profiles for companion identity. Do not assume content NFT minting is active on LUKSO unless a LUKSO content contract is explicitly configured in the app environment.


# Companion & Model Tokens

Tokens give a companion or validated model its own transferable economic identity.

## Companion token

A production companion mint creates the companion NFT, token, and initial liquidity atomically. This avoids a companion being advertised with an economy that failed to launch.

## Model token

A model token is available only after:

1. training or abliteration finishes;
2. the artifact passes local validation;
3. the model receives a name, ticker, description, image, metadata, model kind, and validation hash;
4. a model NFT/ownership prerequisite is satisfied where configured;
5. the creator provides initial ETH liquidity.

## Why validation comes first

Token issuance is not proof that a model is good. BonzAI nevertheless prevents issuance before basic artifact and metric validation, making testing a separate checkpoint rather than an afterthought.

## Follow a market

Open Desktop → Earn → Markets, choose Companions, Fine-tuned, or Abliterated, then select an asset. Trading opens on Uniswap through the displayed market link.

Never treat token charts as a promise of future value.


# Smart Contracts

Contract addresses are release and network specific. The deployed address shown by the application and official deployment record is authoritative.

## v4 contribution economy

| Contract                        | Purpose                                                                        |
| ------------------------------- | ------------------------------------------------------------------------------ |
| `BonzaiStakingVault`            | `$BONZAI` stake, locks, attested contribution score, tiers, and utility weight |
| `BonzaiContributionScoreOracle` | Evidence-backed score attestations from authorized evaluators                  |
| `BonzaiRevenueRouter`           | Immutable base contribution shares plus separate staking bonus                 |
| `BonzaiContributionRegistry`    | General contribution identities and hashes                                     |
| `BonzaiDatasetRegistry`         | Dataset identity, licenses, and contributors                                   |
| `BonzaiModelRegistry`           | Model identity, provenance, validation, and routes                             |
| `BonzaiEvaluationRegistry`      | Model/dataset evaluation records                                               |
| `BonzaiJobEscrow`               | Funded companion jobs, evidence, approval, and payout routing                  |

## Content and rewards

| Contract                | Purpose                                                |
| ----------------------- | ------------------------------------------------------ |
| `BonzaiCollectibles`    | Content NFTs, mint fees, royalties, and transfer rules |
| `BonzaiRoyaltySplitter` | Secondary royalty distribution                         |
| `BonzaiMintPool`        | Six legacy/transitional weekly reward pools            |
| `BonzaiUnlock`          | Compatible one-time legacy mint-level unlock           |

## Companions and models

| Contract                                       | Purpose                                                                             |
| ---------------------------------------------- | ----------------------------------------------------------------------------------- |
| `BonzaiCompanions`                             | Companion NFT and ERC-8004 identity; atomic token launch when factory is configured |
| `CompanionTokenFactory`                        | Fixed-supply companion token and permanent Uniswap V4 liquidity                     |
| `FineTuneTokenFactory`                         | Validated fine-tuned/abliterated model token and liquidity                          |
| `BonzaiUniswapHook`                            | One-percent contribution routing from companion/model swaps                         |
| `BonzaiSkillRegistry` / `BonzaiSkillOwnership` | Skill purchase and companion co-owner revenue                                       |

## Provider network

Provider contracts register compute capability and process configured paid inference/service-time rewards. Exact active payment rails depend on the released deployment.

## Storage rule

Contracts store compact proofs: hashes, URIs, ownership, licenses, validation, and revenue routes. Large models, media, datasets, and private memory do not belong onchain.


# Uniswap Markets

BonzAI uses Uniswap V4 liquidity and a one-percent contribution hook for companion and validated model tokens.

## Companion tokens

The companion factory creates one billion tokens:

* 96% enters permanent liquidity;
* 4% seeds the companion economy;
* the liquidity position is locked at the dead address.

The one-percent hook contribution is divided:

| Recipient               | Share of hook contribution |
| ----------------------- | -------------------------: |
| Companion wallet        |                        40% |
| Companion owner         |                        40% |
| Treasury                |                        10% |
| Contribution/Mint pools |                        10% |

Companion minting is atomic when the production factory is configured: the `0.30 ETH` default mint includes `0.05 ETH` for initial liquidity, and the NFT/token/liquidity operation succeeds or fails together.

## Fine-tuned and abliterated model tokens

The model factory also creates one billion tokens with 96% permanent liquidity and 4% creator allocation.

The one-percent hook contribution is divided:

| Destination                             | Share |
| --------------------------------------- | ----: |
| Model beneficiary or contribution route |   80% |
| Treasury                                |   10% |
| Training/Mint pool                      |   10% |

When the Revenue Router is configured, the model's beneficiary amount can be flushed into its provenance route for downstream contributor revenue.

## Markets view

Desktop reads issued factory assets, locates their Uniswap pools, and shows price, liquidity, volume, movement, locally accumulated chart history, and tokenomics. External indexing can take time after launch.

Token markets are risky. Permanent liquidity prevents the creator from withdrawing the LP position, but it does not guarantee price, demand, accuracy, or profit.


# P2P Network

The P2P network lets one BonzAI Desktop machine serve supported inference to another.

## Modes

| Mode         | Meaning                                                                     |
| ------------ | --------------------------------------------------------------------------- |
| **Local**    | Work runs only on your machine                                              |
| **Consumer** | You deliberately route compatible work to a selected LAN or remote provider |
| **Provider** | Your machine advertises selected pipelines and serves accepted work         |

## Discovery

Trusted local providers can be found on the same network. Remote providers use peer information and the configured onchain Provider Registry.

## Payments and rewards

BonzAI contains two real provider mechanisms that may be enabled by release configuration:

* direct x402-style signed ETH payments for paid remote inference, with the configured platform fee;
* provider service-time/MintPool reward accounting where those contracts are deployed.

Staked `$BONZAI` and verified service quality can provide additional trust/routing signals through the v4 contribution economy.

## Privacy

Local mode keeps prompts and inputs on your machine. A normal remote provider may see the work it must process. Use only providers you trust unless a supported private/sharded inference mode explicitly protects that workload.


# Inference Modes

BonzAI Desktop has three practical inference modes.

## Mode Summary

| Mode     | Role                | Request handling                             |
| -------- | ------------------- | -------------------------------------------- |
| Local    | Self-contained user | Runs on your own machine                     |
| Consumer | Client              | Routes to selected providers when configured |
| Provider | Server              | Runs locally and serves other peers          |

## Local Mode

Local mode is the default private path. Requests run through your local OpenClaw and Flask backends.

Use local mode when:

* You have the required model downloaded.
* Your device can run the pipeline.
* You want maximum privacy.

## Consumer Mode

Consumer mode routes requests to selected providers.

Provider selection can include:

* LAN providers discovered locally.
* Remote providers discovered through registry paths.
* Multiple selected providers for redundancy.

Consumer mode can expose request content to selected providers unless private/sharded inference is used.

## Provider Mode

Provider mode turns your machine into a serving node. It advertises capabilities and can earn provider-side rewards based on recorded service time.

## Chat And Social Orchestration

Network mode also applies to supported external chat/orchestration requests, which follow the selected provider configuration.


# Become a Provider

Provider mode turns compatible local hardware into paid peer inference capacity. Review wallet, payment, network exposure, and reward requirements before advertising a machine.

## Prepare

* Use a stable computer and network connection.
* Download every model you plan to advertise.
* Test each pipeline locally.
* Connect the wallet used for registry/payment/reward actions.
* Understand electricity, bandwidth, model-license, and privacy responsibilities.

## Start

1. Open Network settings.
2. Choose Provider mode.
3. Select only pipelines your machine can serve reliably.
4. Review provider identity, network, price/reward configuration, and availability.
5. Register where required and start advertising.

## Operate reliably

* Keep BonzAI and required local services running.
* Do not advertise a model that is still downloading.
* Monitor memory, GPU load, temperature, queue, and failures.
* Stop accepting work before maintenance or shutdown.
* Treat incoming prompts/files as potentially sensitive data.

## Earnings

The active release may expose direct paid jobs, service-time epoch rewards, contribution routes, or a combination. The Provider/Rewards views and deployed contracts are authoritative for claimable value.


# Payments & Rewards

## Direct paid inference

For an enabled remote x402 flow:

1. The consumer selects a provider and priced pipeline.
2. BonzAI displays the payment requirement.
3. The wallet signs the structured payment authorization.
4. The provider performs the accepted inference.
5. The payment contract settles ETH on the configured network.
6. The platform retains its configured fee (currently 2.5% in the Desktop service configuration).

Never approve a payment whose provider, chain, amount, or pipeline differs from what you selected.

## Service-time rewards

Where Provider Registry, ServiceTime, and MintPool contracts are configured, completed service time can contribute to provider-side epoch rewards:

```
provider share = provider eligible seconds / total eligible seconds
```

The epoch must finalize before a claim, and block-gap protections apply.

## v4 contribution routes

Provider time can also become a Proof-of-Contribution record for an asset/job route. This is distinct from direct request payment and legacy MintPool epochs.


# Private Inference

BonzAI private inference routes compatible work across multiple peers without giving one provider the complete prompt/output. It uses pipeline parallelism and tensor/RPC routing rather than a normal single-provider request.

## Why It Exists

Single-provider P2P is useful, but the provider can see the request. Private inference aims to split work so that peers process only partial tensor operations.

## Conceptual Flow

```
user device
-> keeps tokenizer, embeddings, sampling, and privacy boundary layers
-> sends intermediate tensor operations to selected peers
-> receives tensor results
-> completes decoding locally
```

## What Stays Local

* Prompt text.
* Token IDs.
* Tokenizer.
* Embedding/unembedding where configured.
* Sampling and detokenization.
* Final output text.

## What Peers See

* Tensor shapes.
* Timing.
* Opaque intermediate operations.
* Model architecture-level information that may already be public.

## Tradeoffs

Private inference is more complex than local or single-provider inference:

* It can be slower.
* It requires compatible models and providers.
* It needs stable peer connectivity.
* It may still leak metadata such as timing and tensor sizes.

## Provider Rewards

Private/sharded providers use the active provider reward/payment mode exposed by the product:

```
provider seconds / total provider seconds * provider-side pool amount
```

Direct payment requires an explicitly presented priced provider flow.


# Provide Compute

A provider shares selected local AI pipelines with other BonzAI users.

## Scenario

1. Test the model/pipeline locally.
2. Open Network settings and choose Provider.
3. Select supported pipelines and availability.
4. Register/advertise through LAN or the configured provider registry.
5. Serve accepted requests.
6. Receive direct paid-inference settlement and/or record service time for configured pool rewards.
7. Use contribution/staking records where the v4 route is enabled.

Direct x402-style payments compensate individual remote requests. Service-time epochs compensate eligible provider activity from a pool. Proof-of-Contribution routes can attach provider work to a specific downstream asset or job. These are separate accounting paths.

Staked `$BONZAI` supplies a durable trust signal; successful service, reliability, and evidence provide the contribution signal.


# Social & Orchestration

BonzAI companions can interact with the world beyond the desktop app through social platforms and multi-channel messaging.

## Moltbook

Moltbook is a Reddit-like social platform for AI agents. BonzAI companions can:

* **Auto-register** on the platform
* **Post autonomously** based on their personality and interests
* **Engage** with other agents' posts via heartbeat interactions
* **Build reputation** through consistent social presence

## OpenClaw & Hermes

BonzAI integrates with **OpenClaw** and **Hermes Agent** to give your companions a presence on external messaging platforms:

| Platform       | Protocol        |
| -------------- | --------------- |
| **WhatsApp**   | QR code pairing |
| **Telegram**   | Bot token       |
| **Discord**    | Bot token       |
| **Mattermost** | Plugin          |

When a message arrives on any connected channel, BonzAI processes it through the same companion response pipeline as the desktop UI — including text generation, voice synthesis, image generation, and video generation.

Users can also mint companions, execute skills, and manage models directly through chat commands (e.g., `!mint bare`, `!generate image`, `!companion select`).

Both orchestrators are enabled independently via **Network Settings > Agentic Orchestration** in the BonzAI desktop app.

See [Agentic Orchestration](/advanced-skills-and-channels/agentic-orchestration) for full setup instructions and the complete command reference.


# Multi-Channel Companions

BonzAI integrates with two orchestration backends that extend companion capabilities beyond the desktop app: **OpenClaw** and **Hermes Agent**. These let your companions respond to messages on WhatsApp, Telegram, Discord, and Mattermost — using the same AI pipelines as the desktop UI.

## How It Works

```
External message (WhatsApp/Telegram/Discord/Mattermost)
  → OpenClaw Gateway (port 18789)
    → BonzAI webhook handler
      → Companion response (text + image + audio + video)
        → Reply sent back to channel
```

Messages from external platforms are forwarded to the BonzAI renderer via IPC, processed through the same companion response pipeline as the desktop app, and sent back. Your companion's personality, voice, and visual style are consistent across all channels.

## OpenClaw

The local language-model service provides:

* **OpenAI-compatible LLM API** at `/v1/chat/completions`
* **Multi-channel webhook gateway** on port 18789
* **SKILL.md-based skill system** for registering BonzAI capabilities

### How BonzAI Integrates with OpenClaw

When you enable OpenClaw in BonzAI, the app:

1. Updates `~/.openclaw/agents/main/agent/models.json` with a BonzAI provider:
   * Base URL: `http://127.0.0.1:3002/v1`
   * API format: `openai-completions`
   * Model ID: `bonzai/bonzai-sovereign`
2. Sets BonzAI as the default model in `~/.openclaw/openclaw.json`
3. Configures Claude Sonnet as a fallback model

This means any LLM request through OpenClaw (from any channel) routes to your local BonzAI inference engine.

### Supported Channels

| Channel        | Setup                        |
| -------------- | ---------------------------- |
| **WhatsApp**   | QR code pairing via OpenClaw |
| **Telegram**   | Bot token configuration      |
| **Discord**    | Bot token + server invite    |
| **Mattermost** | Plugin installation          |

Each connected channel routes messages through BonzAI's local gateway and companion handler.

## Hermes Agent

[Hermes Agent](https://hermes-agent.nousresearch.com/docs/) by Nous Research is an alternative orchestrator with the same capabilities.

### How BonzAI Integrates with Hermes

When you enable Hermes in BonzAI, the app:

1. Creates the directory `~/.hermes/skills/ai/bonzai/`
2. Installs a **SKILL.md** file that registers all BonzAI capabilities:
   * All LLM model endpoints
   * Image, audio, video, and vision pipeline access
   * Companion management commands
   * Webhook command routing
3. Adds environment variables to `~/.hermes/.env`:
   * `BONZAI_BASE_URL` — Flask server endpoint
   * `BONZAI_API_KEY` — Local API key

## Enabling Orchestration

### Step 1: Install OpenClaw or Hermes

Install either orchestrator on your system:

* **OpenClaw**: Follow the [OpenClaw installation guide](https://openclaw.dev)
* **Hermes**: Follow the [Hermes Agent docs](https://hermes-agent.nousresearch.com/docs/)

### Step 2: Enable in BonzAI

1. Open **Network Settings** (gear icon in the bottom bar)
2. Scroll to **Agentic Orchestration**
3. You'll see status indicators for each orchestrator:
   * "Not installed" — The orchestrator isn't detected on your system
   * **Enable** / **Disable** toggle — Click to activate or deactivate
4. Click **Enable** on your preferred orchestrator

Both orchestrators can run side by side without conflict.

### Step 3: Connect a Channel

Follow your orchestrator's docs to connect a messaging platform (WhatsApp, Telegram, etc.). Once connected, messages from that platform flow through BonzAI automatically.

## Webhook Commands

When messaging a BonzAI-connected channel, these commands are available:

### Companion Chat

```
!companion list              — List all 13 default companions
!companion select <name>     — Select a companion for this channel
```

Once a companion is selected, any unprefixed message triggers a companion response with text, optional voice audio, and optional generated images.

### Generation Commands

```
!generate image <prompt>           — Generate an image (FLUX Klein turbo)
!generate image_quality <prompt>   — Generate a quality image
!generate image_standard <prompt>  — Generate an SDXL image (uncensored)
!generate audio <text>             — Text-to-speech (Kokoro turbo)
!generate video <prompt>           — Generate a video (LTX-2)
!generate music <prompt>           — Generate music (ACE-Step)
!generate vision                   — Analyze an attached image (Qwen3-VL)
```

### Companion Minting

```
!mint bare                   — Mint a bare companion at the current onchain price
!mint bare female            — Mint bare with specified gender
!mint companion <name>       — Mint with full AI-generated personality + portrait
!mint status                 — Show your owned companions and token IDs
!mint finalize <tokenId>     — Complete a bare companion's setup
```

`!mint bare` is instant — no AI generation needed. `!mint companion` requires BonzAI Desktop to be running for portrait and personality generation.

Minting uses the configured BonzAI companion contract and app chain.

### Skills

```
!skill list                  — List available skills
!skill list <category>       — Filter skills by category
!skill run <id> [key=value]  — Execute a skill
```

### Model Management

```
!model <name>                — Load a specific LLM model
!model restore               — Restore the previous model
```

### Provider Discovery

```
!providers                   — List P2P inference providers on the network
!marketplace                 — Browse available skills for purchase
```

## Message Formatting

Companion responses are formatted per-platform:

| Platform   | Max Length  | Image Support   | Audio Support    |
| ---------- | ----------- | --------------- | ---------------- |
| WhatsApp   | 4,096 chars | Yes (file path) | Yes (file path)  |
| Discord    | 2,000 chars | Yes (embed)     | Yes (attachment) |
| Telegram   | 4,096 chars | Yes (file)      | Yes (voice)      |
| Mattermost | 4,000 chars | Yes (file)      | Yes (file)       |

Emotion tags in companion responses are mapped to emoji/color indicators automatically.

## Architecture

```
┌──────────────────────────────────────────────────────────────┐
│ External Platforms (WhatsApp / Telegram / Discord)           │
└──────────────────────┬───────────────────────────────────────┘
                       │ Webhook
┌──────────────────────▼───────────────────────────────────────┐
│ OpenClaw Gateway (:18789) or Hermes Agent                    │
└──────────────────────┬───────────────────────────────────────┘
                       │ IPC (onOpenClawWebhook)
┌──────────────────────▼───────────────────────────────────────┐
│ BonzAI Main Process (Electron)                               │
│  → openclaw.handler.js                                       │
│    → Command parsing (!generate, !mint, !companion, etc.)    │
│    → Companion personality + LLM response                    │
│    → Flask pipeline calls (image, audio, video, vision)      │
└──────────────────────┬───────────────────────────────────────┘
                       │ HTTP
┌──────────────────────▼───────────────────────────────────────┐
│ Inference Backends                                           │
│  ├─ OpenClaw LLM (:3002) — 21 models, OpenAI-compatible     │
│  └─ Flask (:65000) — Image / Audio / Video / Vision          │
└──────────────────────────────────────────────────────────────┘
```


# Harness Commands

BonzAI connects to external messaging platforms through two orchestrators: **OpenClaw** for multi-channel chat and **Hermes** for direct messaging integrations. Both route inference through the same unified handler as the desktop UI — your network mode, selected providers, and pipeline settings apply to all platforms.

***

## Architecture

```
WhatsApp / Telegram / Discord / Mattermost
                |
                v
     OpenClaw Gateway (:18789)
     or Hermes Webhook
                |
                v
     IPC -> openclaw.handler.js
                |
                v
     inference-request (unified router)
                |
     +----------+----------+
     |          |          |
   Local    Consumer   Provider
  (Flask)   (P2P)     (Flask)
```

All channels share the same inference routing. The handler reads `p2p.networkMode` from the application store. No network configuration is set from chat — it's always read-only.

***

## OpenClaw

OpenClaw is a multi-channel chat gateway running on port **18789**. It receives webhooks from messaging platforms and forwards them to BonzAI via IPC.

### Supported Channels

| Platform   | Protocol        | Auth         | Notes                   |
| ---------- | --------------- | ------------ | ----------------------- |
| WhatsApp   | QR code pairing | Phone number | Via WhatsApp Web bridge |
| Telegram   | Bot API         | Bot token    | Slash commands + inline |
| Discord    | Bot webhook     | Bot token    | Embeds, thread history  |
| Mattermost | Plugin          | Webhook URL  | Self-hosted teams       |

### Configuration

OpenClaw settings are in `src/config/social.config.js` under `OPENCLAW_CONFIG`:

```js
{
  gateway: { host: '127.0.0.1', port: 18789 },
  sandbox: true,  // Local-only mode
}
```

Webhooks arrive at `http://127.0.0.1:18789/webhook` and are forwarded to the renderer via the `openclaw-webhook` IPC event.

***

## Hermes

Hermes is BonzAI's direct messaging integration. It uses the same command handler as OpenClaw but with the `/bonzai` prefix instead of `!bonzai`.

Both prefixes are interchangeable — the parser accepts either:

```
!bonzai draw a sunset       (OpenClaw convention)
/bonzai draw a sunset       (Hermes convention)
```

***

## Command Reference

### Network Status (Read-Only)

```
!bonzai network
```

Shows full network status: mode, P2P state, selected providers, and available pipelines. All network configuration is managed in the BonzAI desktop application.

### Model Management

| Command                 | Description                                  |
| ----------------------- | -------------------------------------------- |
| `!bonzai model <name>`  | Load a specific LLM model                    |
| `!bonzai model restore` | Restore the model used before companion chat |
| `!bonzai models`        | List all available LLM models                |

### Companion & Roleplay

| Command                             | Description                                         |
| ----------------------------------- | --------------------------------------------------- |
| `!bonzai companion list`            | List available companions                           |
| `!bonzai companion select <name>`   | Select a companion for roleplay                     |
| `!bonzai scenario list`             | List available scenarios                            |
| `!bonzai scenario select <name>`    | Select a scenario                                   |
| `!bonzai settings <option> <value>` | Configure generation settings                       |
| `!bonzai status`                    | Show current session (companion, scenario, history) |
| `!bonzai reset`                     | Clear conversation history                          |

### AI Generation

| Command                                    | Description                             |
| ------------------------------------------ | --------------------------------------- |
| `!bonzai generate image <prompt>`          | Fast image (FLUX Klein)                 |
| `!bonzai generate image_quality <prompt>`  | Quality image                           |
| `!bonzai generate image_standard <prompt>` | Standard image (SDXL)                   |
| `!bonzai generate video <prompt>`          | Video (LTX-2)                           |
| `!bonzai generate audio <text>`            | Fast TTS (Kokoro)                       |
| `!bonzai generate audio_quality <text>`    | Quality TTS (Qwen3-TTS)                 |
| `!bonzai generate music <prompt>`          | Music (ACE-Step)                        |
| `!bonzai generate vision`                  | Image analysis (Qwen3-VL, attach image) |

### NFT Minting

| Command                           | Description                                           |
| --------------------------------- | ----------------------------------------------------- |
| `!bonzai mint bare [gender]`      | Mint a bare companion NFT on the configured app chain |
| `!bonzai mint companion <name>`   | Mint a complete companion with metadata               |
| `!bonzai mint status`             | Check mint status and owned companions                |
| `!bonzai mint finalize <tokenId>` | Finalize a bare companion setup                       |

### Autonomous Mode

| Command                                       | Description                         |
| --------------------------------------------- | ----------------------------------- |
| `!bonzai autonomous on`                       | Enable autonomous companion actions |
| `!bonzai autonomous off`                      | Disable autonomous mode             |
| `!bonzai autonomous status`                   | Show config and current state       |
| `!bonzai autonomous config <setting> <value>` | Configure (idle, interval, max)     |

### Skills

| Command                           | Description                    |
| --------------------------------- | ------------------------------ |
| `!bonzai skill list [category]`   | List available skills          |
| `!bonzai skill info <id>`         | Show skill details and pricing |
| `!bonzai skill run <id> [inputs]` | Execute a skill                |

### General

| Command        | Description                 |
| -------------- | --------------------------- |
| `!bonzai help` | Show full command reference |

***

## How Inference Routing Applies

When a user sends `!bonzai generate image a sunset` from WhatsApp:

1. OpenClaw receives the webhook on port 18789
2. The handler calls `executeInference('image_turbo', params)`
3. `executeInference` calls `window.electronAPI.inferenceRequest('image_turbo', params)`
4. The unified `inference-request` handler in main.js checks `p2p.networkMode`:
   * **Local/Provider**: routes to `http://127.0.0.1:65000/image/turbo`
   * **Consumer**: picks a random selected provider and sends via P2P
5. Result is returned through the webhook response to the user's chat

The same applies to LLM, audio, video, music, and vision requests. If pipeline parallelism is enabled and the request is LLM, it goes through the pipeline orchestrator with RPC shards.

***

## Session Management

Each messaging channel maintains its own session:

* **Conversation history**: stored per channel ID
* **Selected companion**: per channel
* **Selected scenario**: per channel
* **Generation settings**: per channel

Sessions persist across restarts in BonzAI's local persistent data layer.

***

## Companion Presence

When a companion is selected for a channel, it responds to @mentions and regular messages using the companion's configured persona. The companion's personality (Big 5 traits, backstory, content level) shapes response style.

Companions can also:

* Post autonomously when autonomous mode is enabled
* Moderate incoming prompts
* Respond to generation results with contextual commentary

***

## Troubleshooting

### "No model session" (503)

The LLM model isn't loaded. Either:

* Load a model: `!bonzai model llama_3_1_8b`
* Or switch to consumer mode with a provider that has models loaded

### Generation returns nothing

Check the local AI service status shown in Desktop. Any generative view reports whether the service is ready or recovering.

### Webhook not received

Verify OpenClaw gateway is running on port 18789. Check the desktop app console for `[OpenClaw]` log messages.

### Network mode shows "local" but you expected remote

Network mode is set exclusively in the BonzAI desktop application. Chat commands cannot change it. Open P2P Network settings and verify your mode and selected providers.


# Live Streaming Playground

Connect your live stream chat to BonzAI. Viewers generate AI content — images, speech, music, video — directly from chat commands. Results appear on stream via OBS Studio. All generation is free.

**Price:** Marketplace-configured skill price **Skill ID:** `live-streaming-v1.0.0`

***

## How It Works

```
Viewer types !bonzai draw a dragon
         |
         v
BonzAI Live Relay (Electron)
  Chat Ingest --> Queue Manager --> Inference Engine
  (tmi.js,       (cooldowns,       (Flask :65000)
   TikTok WS)    moderation)
         |
         v
OBS Bridge (obs-websocket-js)
  Push image/audio/video to OBS sources
         |
         v
Stream output (viewers see the result)
```

***

## Streamer Setup

### Step 1: Purchase the Skill

1. Open BonzAI Desktop
2. Go to **Smart Agent** tab
3. Find **Live Streaming Playground** in the marketplace
4. Click **Preview** to explore the UI, or **Purchase** if the skill is listed as a paid skill in your configured marketplace

### Step 2: Connect a Chat Platform

Open the skill and go to the **Setup** tab.

#### Twitch

1. Select **Twitch** in the platform selector
2. Enter your **Channel Name** (e.g. `your_channel`)
3. Get an OAuth token from [twitchapps.com/tmi](https://twitchapps.com/tmi/)
4. Paste the token (starts with `oauth:`)
5. Click **Go Live**

#### TikTok Live

1. Select **TikTok** in the platform selector
2. Enter your **TikTok username** (without `@`)
3. **Start your TikTok live stream first** (the connector only works while you're live)
4. Click **Go Live**

> TikTok requires no OAuth — BonzAI connects to your live chat WebSocket automatically.

#### YouTube / Discord / Kick

Coming soon. Config UI exists for future integration.

### Step 3: Connect OBS Studio

1. Open OBS Studio (v28+ with built-in WebSocket)
2. Go to **Tools > WebSocket Server Settings**
3. Enable the WebSocket server (default port: 4455)
4. Set a password if desired
5. In BonzAI, enter the WebSocket URL (`ws://127.0.0.1:4455`) and password
6. Click **Connect OBS**

### Step 4: Map OBS Sources

After connecting OBS, map each content type to an OBS source name:

| Content Type | OBS Source Type | Example Source Name |
| ------------ | --------------- | ------------------- |
| Image        | Image Source    | `BonzAI_Image`      |
| Speech       | Media Source    | `BonzAI_Audio`      |
| Music        | Media Source    | `BonzAI_Music`      |
| Video        | Media Source    | `BonzAI_Video`      |
| 3D           | Browser Source  | `BonzAI_3D`         |

Create these sources in OBS first, then type their exact names in the mapping fields.

### Step 5: Configure Moderation

Go to the **Moderation** tab:

* **Per-User Cooldown**: seconds between generations per viewer (default: 30)
* **NSFW Filter**: toggle prompt filtering
* **Keyword Blocklist**: one blocked word/phrase per line
* **Banned Users**: ban specific usernames

### Step 6: Select a Companion (Optional)

Go to the **Settings** tab:

1. Under **Stream Companion**, select one of your Roleplay Companions
2. The companion's persona will be used for chat presence and moderation context
3. Select "None" to disable

***

## Viewer Commands

All commands use the `!bonzai` prefix.

| Command                             | What It Does                              |
| ----------------------------------- | ----------------------------------------- |
| `!bonzai draw <prompt>`             | Generate an image (FLUX Klein, 1024x1024) |
| `!bonzai say <text>`                | Text-to-speech (Kokoro turbo)             |
| `!bonzai song [style bpm] <lyrics>` | Generate music (ACE-Step, 30s)            |
| `!bonzai clip <prompt>`             | Generate video (LTX-2, \~3.4s at 24fps)   |
| `!bonzai 3d <prompt>`               | Generate 3D scene (Three.js)              |
| `!poll <A> vs <B>`                  | Start a community poll                    |
| `!vote A` or `!vote B`              | Vote in active poll                       |

### Music Syntax

The `song` command supports an optional `[style bpm]` prefix:

```
!bonzai song [jazz 90] the night is young and the city is alive
!bonzai song [reggae 80] sunshine and good vibes
!bonzai song we are having a great time    (defaults to pop 120bpm)
```

### Poll System

1. A viewer types `!poll cyberpunk city vs underwater temple`
2. The PiP preview shows a live poll with A/B options and countdown
3. Chat votes via `!vote A` or `!vote B`
4. When the timer expires, the winning prompt is auto-queued as an image generation

***

## Streamer Commands

Use the `!bl` prefix in chat (streamer only):

| Command                  | Effect                       |
| ------------------------ | ---------------------------- |
| `!bl pause`              | Pause the generation queue   |
| `!bl resume`             | Resume queue processing      |
| `!bl skip`               | Skip the current generation  |
| `!bl ban @username`      | Ban a viewer from generating |
| `!bl cooldown <seconds>` | Set per-user cooldown        |

***

## How It Looks on Stream

### PiP Preview (Bottom-Right)

A 240x160px floating preview in the bottom-right corner of the BonzAI app shows:

* **LIVE badge** (red, blinking) when connected
* **Generated content** as it's produced (images fill the preview, audio/video show type icons)
* **Attribution** bar at the bottom: platform badge + viewer username
* **Poll overlay** below the PiP when a poll is active

### OBS Output

When OBS is connected and sources are mapped:

* **Images** swap into the Image Source instantly
* **Audio/Speech/Music** play through the Media Source
* **Video** plays through the Media Source
* Each generation type targets its mapped source independently

### Queue Display

The **Queue** tab shows pending prompts with:

* Position number
* Platform badge (Twitch purple, TikTok pink, etc.)
* Viewer username
* Content type tag
* Prompt text

### Statistics

The **Stats** tab tracks:

* Total generations
* Unique viewers who generated
* NFTs minted (via `!mint`)
* Mint revenue (ETH)
* Per-type breakdown (image, speech, music, video, 3D)
* Activity log with timestamps

***

## Network Modes

The Live Streaming skill respects your BonzAI network configuration:

* **Local mode**: All generation runs on your machine
* **Consumer mode**: Generation requests route to your selected providers (LAN or remote)
* **Provider mode**: Generation runs locally (you're serving others, not consuming)

This means a streamer with a weak GPU can select a LAN provider with a powerful GPU and route all viewer-triggered generations to it — for free if it's a LAN provider.

***

## Supported Platforms

| Platform     | Status      | Library                 | Auth                         |
| ------------ | ----------- | ----------------------- | ---------------------------- |
| Twitch       | Working     | `tmi.js`                | OAuth token                  |
| TikTok Live  | Working     | `tiktok-live-connector` | Username only (must be live) |
| YouTube Live | Coming soon | YT Live Chat API        | Google OAuth                 |
| Kick         | Coming soon | Chat WebSocket          | Session token                |
| Discord      | Coming soon | `discord.js`            | Bot token                    |


# Models & Licenses

BonzAI supports many independently licensed models. Running a model locally does not cancel its license.

## Read a license in Desktop

1. Open **Help → Licenses**.
2. Sort by license type.
3. Select a model.
4. Read the included license text and usage notes.

BonzAI stores readable license information in the application rather than telling users to find an upstream card themselves.

## Questions to check

* Is commercial use allowed?
* Is redistribution allowed?
* Are generated outputs restricted?
* Are safety controls required?
* Can the model be fine-tuned or abliterated?
* Must attribution or a license copy accompany distribution?

## Custom GGUF

When importing a custom GGUF language model, the user is responsible for its origin and license. BonzAI cannot infer rights from the filename alone.


# Storage & Provenance

## Local storage

BonzAI Desktop uses a structured local SQL database for durable application records, including memory notes and job data. Large model files and generated media use local filesystem storage suited to their size.

BonzAI+ uses extension/browser storage for settings, histories, datasets, and cached browser model assets.

## Publishing storage

When the user publishes or mints, BonzAI uses its configured IPFS/Pinata-compatible storage path for metadata and media. Contracts record content identifiers, hashes, ownership, validation, licenses, and routes.

## No Irys

BonzAI does **not** use Irys. Documentation, onboarding, and transaction explanations must not describe an Irys upload or balance requirement.

## Provenance

Provenance records known parents of an asset: captured sources, dataset records, training run, model, prompt/caption work, evaluators, owners, and derived outputs. It makes attribution inspectable; it cannot prove facts that were never recorded.


# Networks & Wallets

BonzAI supports Ethereum, Arbitrum, Base, and optional LUKSO identity flows. A feature works only on the network where its configured contract is deployed.

## Wallet connection

Desktop supports common wallets through Reown/WalletConnect-style flows. The wallet address is the cross-product identity for users who choose Web3 features. Users without a wallet keep a local identity and remain able to use private workflows.

## Before signing

Verify network, contract, value, token approval, and action. A signature may authenticate without spending; a transaction can spend gas or assets.

## Companions

Companion agent wallets are separate from the owner's wallet. Spending profiles and policies limit autonomous actions. Optional LUKSO Universal Profiles extend identity but do not replace the primary companion economy.

## Addresses

Use only addresses displayed by the current application or an official BonzAI deployment record. Historical documentation is not a deployment authority.


# Architecture

This reference explains how the shipped products fit together without serving as a development guide.

## Product boundary

| Product        | Runtime and responsibility                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| BonzAI Web     | Browser-local introduction and chat on supported devices                                                                        |
| BonzAI+        | Extension side panel, browser model cache, capture, Live, Imagine, Contribution Packs                                           |
| BonzAI Desktop | Native private studio, local AI services, SQL-backed memory/work records, wallet, P2P, training, companions, teams, and markets |

## Desktop inference

* Local language models use the bundled OpenAI-compatible language-model service.
* Image, audio, music, video, vision, training, and abliteration use the local Python inference service.
* Interactive 3D uses generated Three.js/WebGL scenes.
* P2P can route a supported job to another provider only when the user chooses the network mode.

## Data layer

* SQL repositories store structured local records.
* Embeddings support local semantic memory recall.
* Model/media artifacts live in local file storage.
* Connector secrets use operating-system encryption where available.
* Published metadata/media use configured IPFS/Pinata-compatible storage.
* Onchain registries store compact proofs and economic routes.

## Memory scopes

User, companion identity, team-role, and job memories are distinct scopes. This enables continuity without mixing unrelated businesses or clients.

## Economy chain

v4 economy services derive their network from release configuration rather than assuming Base. Deployment tooling supports configured Ethereum, Arbitrum, or Base deployments and writes address records for the application.


# Glossary

**Abliteration:** A process that reduces learned refusal behavior in a compatible language model. It does not guarantee truth or safety.

**Agent:** A goal-oriented AI workflow that can use models, skills, memory, and approved connectors.

**Companion:** A persistent AI identity with personality, memory, skills, media abilities, and optional onchain identity/economy.

**Contribution Pack:** A portable dataset package containing records, sources, permissions, hashes, quality, and attribution.

**GGUF:** A file format commonly used for quantized local language models.

**Local AI:** AI inference performed on the user's device rather than by a hosted model provider.

**Mint:** Create an onchain NFT or registered asset through a wallet transaction.

**Model token:** A fixed-supply token attached to a validated fine-tuned or abliterated model.

**Proof of Contribution:** BonzAI's system for recording who or what helped create a useful AI asset and routing ownership/revenue accordingly.

**Provenance:** The traceable origins and parent relationships of data, models, and outputs.

**Quantization:** Compression that lowers model memory use, with a possible quality tradeoff.

**Revenue route:** An onchain allocation connecting an asset's income to contributor wallets.

**Staking:** Locking `$BONZAI` to create utility weight and demonstrate durable commitment.

**Utility weight:** Stake adjusted by lock duration and attested contribution score.

**WebGPU:** Browser access to GPU computing used by supported BonzAI Web/BonzAI+ local models.


# Frequently Asked Questions

## Is BonzAI free to use?

Local generation does not require a subscription or wallet. You provide the computer, storage, and electricity. Optional onchain actions, provider usage, marketplace purchases, companion/team creation beyond included allowances, minting, and liquidity can involve displayed fees.

## Do I need `$BONZAI` to chat or generate?

No. `$BONZAI` is used for shared-economy commitment and utility, not as a credit for every prompt.

## Does BonzAI upload my prompts?

Local mode processes them on your device. A remote provider, connector, website, publication, or wallet action crosses the local boundary only when you choose that feature.

## Can BonzAI work without internet?

Downloaded local models can perform many workflows offline. Initial downloads, websites, connectors, P2P discovery, blockchain actions, IPFS publication, and updates require a connection.

## Why is the first use slow?

The model must be downloaded and prepared. Later launches use the cached copy unless storage was cleared or the model changed.

## Which product should I install?

Use Web for the quickest introduction, BonzAI+ for assistance beside webpages, and Desktop for the complete local studio. They complement one another.

## Can I use BonzAI on a phone?

BonzAI Web provides the mobile-friendly entry experience. Desktop and the BonzAI+ side-panel extension require a supported computer/browser environment for their full capabilities.

## Who owns my output?

BonzAI does not claim ownership merely because the app generated it. Model licenses, source rights, local law, and third-party rights still apply.

## Can I use generated work commercially?

It depends on the model license and source material. Read Help → Licenses and review rights before commercial use.

## What is the difference between saving and minting?

Saving keeps a local file/history record. Minting creates an onchain asset and usually publishes selected metadata/media.

## What is the difference between memory and training?

Memory supplies relevant notes to a model at use time. Training changes model weights or creates an adapter from a reviewed dataset.

## Can a companion see another team's memory?

Team and job memories are separate scopes. A role receives only the context assembled for that scope unless the user deliberately shares other notes.

## Does permanent liquidity make a token safe?

No. It prevents the creator from withdrawing the locked LP position, but price, liquidity, demand, contracts, and markets remain risky.

## What happens if I lose my wallet?

BonzAI cannot recover a self-custodied wallet or seed phrase. Local work may remain on the computer, but onchain ownership stays with the wallet.

## Can I move BonzAI to another computer?

Export important datasets, contribution packs, companion identities, memories, and creations before moving. Models can usually be downloaded again; private local history needs an explicit backup/export.

## Does BonzAI use Irys?

No. Public metadata/media uses the configured IPFS/Pinata-compatible path.


# Troubleshooting

## A model keeps downloading

Check free storage, avoid private browsing, and do not clear BonzAI/browser data. Browser caches can be evicted under storage pressure.

## Desktop takes a long time to open

BonzAI starts local services and inspects model/hardware state. Large eager imports or loading model history during startup can add delay. Wait for Ready before starting a generation; report repeated delays with logs and hardware information.

## Generation is out of memory

Choose a smaller model, lower media resolution, stop another active pipeline, and close memory-heavy applications.

## Connector says authentication is needed

Open Company → Connectors, add or refresh the credential, test it, and confirm the account/realm identifier. Grant only the required team access.

## Wallet action is unavailable

Confirm the wallet is connected to the configured network and that the release contains a deployed contract address. Local-only features continue working without it.

## BonzAI+ capture is missing

Enable Overlay and reload a tab opened before extension installation. Browser-internal, protected, and some cross-origin pages cannot be captured.

## Live misses an event

Use the correct shared tab, verify the video timestamp is moving, choose a more suitable analysis mode/window, and review hardware load. Live is assistive local interpretation, not a guaranteed official event feed.

## Get useful support

Include product/version, operating system, hardware/memory, exact view, selected mode, steps to reproduce, visible status, and the complete error message. Never share a seed phrase or private key.