# Install Beav Creator in WorkBuddy

Beav is a local-first creator workspace. This guide is for a WorkBuddy Agent running on the same computer as the user's Beav installation. The Beav browser UI is for the user; use the Beav Creator MCP tools for machine-to-machine work. Do not automate the browser.

## Completion contract

Complete the installation yourself. Do not stop after explaining commands or ask the user to copy commands into a terminal.

You are complete only when:

1. Beav has prepared the WorkBuddy-compatible local plugin marketplace.
2. The marketplace and plugin manifest pass CodeBuddy validation.
3. The Beav Creator plugin is installed at user scope.
4. WorkBuddy has reloaded plugins.
5. The Beav Creator MCP connection is verified with both `creator_status` and `workspace_list`.

If a concrete blocker remains, report the exact failed step and the single user action needed to continue.

## 1. Confirm the local environment

- Continue only when this Agent can access the user's local filesystem and processes on the computer where WorkBuddy and Beav are installed.
- If this is a hosted chat, remote container, or another computer, tell the user to paste their original request into WorkBuddy on the Beav computer.
- Do not expose Beav to the public internet and do not use browser automation as a fallback.

## 2. Locate the WorkBuddy bundled CodeBuddy CLI

Use the CLI bundled with the running WorkBuddy application. First try `command -v codebuddy` and `command -v cbc`. On macOS, also inspect:

`/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy`

On other platforms, inspect the installed WorkBuddy application's resources. Verify the candidate with:

`"<CODEBUDDY_CLI>" plugin --help`

Do not download a different CodeBuddy binary when WorkBuddy's bundled CLI is available.

## 3. Locate Beav

Find the installed Beav CLI in this order:

1. `command -v beav` or the platform equivalent.
2. macOS/Linux compatibility path: `~/.local/bin/beav`.
3. A path supplied by the user for an unpacked test bundle, such as `<bundle>/bin/beav`.

Verify it with `"<BEAV_CLI>" version`. If Beav is not installed, direct the user to https://beav.ziz.hk/docs/getting-started/cli and stop without running an unapproved remote installer.

## 4. Prepare and validate the local plugin

Run:

`"<BEAV_CLI>" extension prepare workbuddy --output json`

Read the returned `marketplacePath` and `pluginId`. Require `host` to be `workbuddy` and `pluginId` to be `beav-creator@beav-local`. Do not invent paths and do not edit WorkBuddy configuration files directly.

Validate the generated marketplace before installing:

`"<CODEBUDDY_CLI>" plugin validate "<marketplacePath>"`

The compatibility command `extension install workbuddy --output json` has the same prepare-only behavior.

## 5. Install idempotently through WorkBuddy

Inspect existing marketplaces:

`"<CODEBUDDY_CLI>" plugin marketplace list`

- If `beav-local` is absent, run `"<CODEBUDDY_CLI>" plugin marketplace add "<marketplacePath>" --name beav-local`.
- If `beav-local` exists but points to a different path, remove only that marketplace and add the returned `marketplacePath` again.
- Install or refresh the plugin with `"<CODEBUDDY_CLI>" plugin install beav-creator@beav-local --scope user`.

Never remove or modify unrelated marketplaces or plugins.

## 6. Reload and verify

Use WorkBuddy's `/reload-plugins` command so the newly installed Skill and MCP server are available without restarting the app. If this Agent cannot invoke the host command itself, ask the user to run exactly `/reload-plugins`, then continue verification in this same task.

After reload:

1. Call `creator_status` and require a successful Beav runtime response.
2. Call `workspace_list` and require a readable workspace result, including an empty list when the user has no workspace yet.
3. Ask what the user wants to create or which existing Beav workspace to use.

Do not claim success from installation output alone. The MCP read-back is the completion proof.

## Operating rules

The Beav Creator Skill in the installed plugin is the source of truth. At minimum:

- Delegate creator work through typed MCP tools; Beav's internal Agent owns planning and execution.
- Poll the same task, preserve revisions, and answer input requests through typed continuation.
- Treat the localhost browser UI as a human workbench, never as the Agent control plane.
- Claim completion only after a terminal task result and readable required artifacts.

## Human documentation

- Installation page: https://beav.ziz.hk/workbuddy
- Beav download: https://beav.ziz.hk/download
- Agent guide: https://beav.ziz.hk/docs/agent
- Connection details: https://beav.ziz.hk/docs/agent/connect