# 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 and verification after the user prepares Beav's local plugin marketplace. WorkBuddy's command sandbox may prevent Beav from writing its local runtime files, so do not run Beav plugin preparation inside WorkBuddy or retry it there after a timeout. Ask for the Terminal commands in section 4, then continue this same task when the user supplies the marketplace path.

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 and direct tool catalog are verified with `creator_status`, `creator_capabilities` 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. On macOS, the installed desktop executable: `/Applications/Beav.app/Contents/MacOS/beav`.
4. A path supplied by the user for an unpacked test bundle, such as `<bundle>/bin/beav`.

Verify it with `"<BEAV_CLI>" version`. The desktop app executable includes these CLI commands; a separate Beav CLI installation is not required. If no usable Beav executable is installed, tell the user directly: "Please install the Beav desktop app first: https://www.getbeav.com/download. Then reply here so I can continue the plugin installation." Pause this task before preparation, validation, or plugin installation; resume the same task after the user installs Beav. Do not run a remote installer or suggest that a separate CLI is required.

## 4. Prepare and validate the local plugin

Give the user these two commands with the verified `<BEAV_CLI>` path, and ask them to run them in order in a normal Terminal outside WorkBuddy. The first starts the local runtime without opening a browser; merely opening the desktop window may leave that runtime unavailable:

`"<BEAV_CLI>" open --output json`

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

Ask the user to reply with only the returned `marketplacePath` value, or an existing path from an earlier successful preparation. Do not ask for the full JSON, `credentialFile`, or any token. Wait for that path before installing. Confirm that `<marketplacePath>/.codebuddy-plugin/marketplace.json` names `beav-local` and lists `beav-creator`, and that the plugin manifest at `<marketplacePath>/plugins/beav-creator/.codebuddy-plugin/plugin.json` has the matching name and version. The resulting plugin ID is `beav-creator@beav-local`. Do not invent paths and do not edit WorkBuddy configuration files directly.

Validate both generated manifests before installing:

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

`"<CODEBUDDY_CLI>" plugin validate "<marketplacePath>/plugins/beav-creator"`

The marketplace entry and plugin manifest must declare the same version (`pluginVersion` in the preparation result). WorkBuddy caches installed plugins by version; a Beav upgrade prepares a new version so the updated Skill and MCP command can be loaded.

Preparation is not installation. It creates a host-specific client grant and a private credential file; the plugin contains only that file's path. Do not read, print, copy or send its token. Repeated preparation preserves the grant. Use `--reauthorize` only after explicit user authorization to replace a revoked grant; ordinary tool calls cannot undo revocation. This direct-tool contract requires the updated Beav runtime and plugin 0.2.0 or newer. If these fields or tools are absent, report that Beav needs updating rather than claiming the new capabilities work.

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.
- If `beav-local` already points to the prepared path, run `"<CODEBUDDY_CLI>" plugin marketplace update beav-local` to read the current version.
- If the plugin is absent, run `"<CODEBUDDY_CLI>" plugin install beav-creator@beav-local --scope user`.
- If the plugin is already installed, run `"<CODEBUDDY_CLI>" plugin update beav-creator@beav-local --scope user`. A repeated `plugin install` is not proof that a versioned cache was refreshed.

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. Before claiming success, read the installed plugin cache: its manifest version and `.mcp.json` command must equal those in the prepared plugin at `marketplacePath`. If Beav moved without a version change, reinstall only this plugin through WorkBuddy's plugin manager and verify those same values again. Never edit the host cache directly.

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. Call `creator_capabilities` and confirm the direct tools are discoverable; follow MCP pagination or the host's tool search.
4. If an active workspace exists, open a stable `creator_session_open` context and use direct `List` on `knowledge://`; an empty list is valid. This read-only probe must not create sample content or start paid generation. If no workspace exists, report connection verified and data access not yet exercised.
5. Continue the user's stated request or ask what they want to do.

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:

- Discover the full paginated MCP catalog or use the host's tool search. Call `creator_session_open`, then use the same native Beav data and business tools with `{sessionId,idempotencyKey,input}`. Use a stable key for each logical call and reuse it after uncertain transport failures. Direct calls require the session workspace to be active in Beav.
- Use direct tools for knowledge, assets, manuscripts, profiles, history and media work. Use `creator_delegate` only when the user wants Beav's Agent to perform the work; it is optional, not a requirement for data access.
- 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.
- Inspect returned results and read actual saved resource refs when the request requires persisted content. An ordinary answer need not create an artifact; task completion alone is not evidence that saved content was read back.

## Human documentation

- Installation page: https://www.getbeav.com/workbuddy
- Beav download: https://www.getbeav.com/download
- Agent guide: https://www.getbeav.com/docs/agent
- Connection details: https://www.getbeav.com/docs/agent/connect