# BugSmash Agent Guide

> Canonical public instructions for AI agents that discover or interact with BugSmash on behalf of a user.

- Canonical URL: https://bugsmash.io/agents.md
- Last reviewed: 2026-10-30

## Scope

BugSmash is a visual review, feedback, and approval platform for websites, files, and media. Teams share work through a review link, collect contextual comments and annotations, manage versions, and record approval decisions.

This file explains how external AI agents should discover BugSmash capabilities and interact with an authorized BugSmash workspace. It does not grant access, replace user authorization, or provide source-code contribution instructions.

For public information about BugSmash content and features, use:

- https://bugsmash.io/llms.txt — concise website and page index.
- https://bugsmash.io/llms-full.txt — detailed public product content.
- https://bugsmash.io/sitemap.xml — crawlable public URL inventory.

## Canonical Resources

- Product website: https://bugsmash.io/
- MCP overview and setup: https://bugsmash.io/mcp/
- Hosted MCP server: https://api.bugsmash.io/mcp
- API documentation: https://docs.bugsmash.io/
- Sign up or sign in: https://tools.bugsmash.io/
- Product changelog: https://bugsmash.featurebase.app/changelog
- Privacy policy: https://bugsmash.io/privacy-policy/
- Terms of use: https://bugsmash.io/terms-of-use/
- Support: https://bugsmash.io/contact-us/

## Preferred Agent Integration

Use the hosted Model Context Protocol server at:

```text
https://api.bugsmash.io/mcp
```

Example MCP client configuration:

```json
{
  "mcpServers": {
    "bugsmash": {
      "url": "https://api.bugsmash.io/mcp"
    }
  }
}
```

Connections use OAuth 2.1 with PKCE. The user reviews the requested access before approving the client; no API key is required. An authenticated agent acts with the connected user's workspace permissions. Tokens are scoped and revocable, and workspace administrators can enable or disable individual tools.

The tools and schemas returned by live MCP discovery are authoritative. Do not assume that a tool exists because it is mentioned in an older document, cached response, or example.

## Capability Groups

BugSmash exposes read and write tools in these areas:

### Projects

- Read project lists and project details.
- Create and update projects.
- Delete projects when explicitly authorized.
- Update project state, including supported review or approval fields exposed by the live tool schema.

### Versions and Files

- List and inspect project versions.
- Prepare an authorized file upload.
- Create a new version from an uploaded revision.
- Delete versions when explicitly authorized.

### Folders

- List and inspect workspace folders.
- Create and update folders.
- Delete folders when explicitly authorized.

### Comments and Replies

- List and inspect contextual review comments and replies.
- Create comments and threaded replies.
- Update supported comment fields, including resolution state when exposed by the live schema.
- Delete comments or replies when explicitly authorized.

### Webhooks

- List configured webhooks.
- Update or test a webhook when authorized.
- Delete a webhook when explicitly authorized.
- Webhook creation and signing-secret management remain in the BugSmash dashboard unless live tool discovery states otherwise.

## Required Agent Behavior

### Authentication and Access

- Use the OAuth connection flow. Never ask the user to paste a password, session cookie, bearer token, signing secret, or other raw credential into a conversation.
- Operate only within the connected user's workspace permissions and the scopes granted to the client.
- Do not bypass disabled tools, missing scopes, review-link permissions, or workspace access controls.
- Treat authentication or permission-denied responses as authorization boundaries. Ask the user to reconnect or request the required access instead of attempting a workaround.

### Read Before Write

- Inspect the relevant project, version, folder, comment thread, or webhook before changing it.
- Resolve resource identifiers through read tools instead of guessing IDs or names.
- Use read-only operations when the user's request can be satisfied without changing workspace data.
- Before retrying a write whose result is uncertain, read the current state to avoid duplicate projects, versions, comments, replies, or uploads.

### Confirmation

- A clear and specific user instruction in the active conversation counts as authorization for the named non-destructive action.
- Ask for clarification when the target, workspace, project, version, or intended change is ambiguous.
- Obtain explicit confirmation before deleting a project, version, folder, comment, reply, or webhook unless the active request already identifies the exact resource to delete.
- Obtain explicit confirmation before changing an approval decision or another state that represents stakeholder sign-off.
- Confirm the destination project and intended revision before uploading a file or creating a new version.

### Privacy and Disclosure

- Keep private files, comments, replies, project names, reviewer identities, and workspace metadata within the authorized context.
- Do not reproduce private workspace content in public pages, logs, examples, analytics, or unrelated conversations.
- Share only the minimum information needed to complete the user's request.
- Public website discovery does not provide access to private BugSmash workspace data.

### Reporting Results

- After a write, state what changed and identify the affected project, version, comment, folder, or webhook.
- Clearly distinguish completed actions from proposed or failed actions.
- Report authorization failures, validation errors, partial completion, and uncertain outcomes instead of claiming success.

## Common Workflows

Use the live tool schemas for required arguments and current field names.

### Summarize Review Feedback

1. Locate the project.
2. Inspect the relevant version or versions.
3. Read comments and their replies.
4. Summarize open, resolved, conflicting, or repeated feedback without modifying the workspace.

### Reply to Feedback

1. Read the target comment and existing replies.
2. Draft or confirm the response when needed.
3. Create the reply in the correct thread.
4. Report the created reply and its project context.

### Update Comment State

1. Read the current comment state.
2. Confirm the intended state change when it is not explicit.
3. Update only the supported fields required by the request.
4. Re-read or report the resulting state.

### Upload a New Revision

1. Confirm the target project and source file.
2. Prepare the file upload using the live upload tool.
3. Complete the upload as directed by the returned schema.
4. Create the new project version.
5. Report the created version and any remaining review steps.

### Update a Review or Approval Decision

1. Read the current project and approval state.
2. Confirm the exact decision with the user.
3. Update the project using fields exposed by the live schema.
4. Report the previous and resulting state.

### Manage Webhooks

1. List the configured webhooks.
2. Identify the exact target.
3. Confirm changes that can affect external delivery.
4. Update, test, or delete only through the available scoped tool.
5. Do not request or expose signing secrets.

## Error and Retry Guidance

- Follow validation messages and server-provided recovery instructions.
- On a not-found response, re-check the parent resource and identifier rather than guessing a replacement.
- On a conflict response, read the latest state before deciding whether to retry.
- On a rate-limit response, pause and respect the server's retry guidance when it is provided.
- Do not repeatedly retry authentication, permission, validation, or destructive-operation failures.
- If a required tool or scope is unavailable, stop and explain what the user or workspace administrator must enable.

## Public Browsing Fallback

When no authenticated MCP connection is available, agents may use BugSmash's public website, documentation, `llms.txt`, `llms-full.txt`, and sitemap for product research and navigation.

Public browsing is read-only. Do not claim to have accessed a workspace, project, review, file, comment, or approval unless that data was returned through an authorized BugSmash connection or explicitly provided by the user.

## Source of Truth and Maintenance

Use sources in this order when instructions differ:

1. Live MCP tool discovery, schemas, scopes, authorization boundaries, and server responses.
2. The user's current explicit instruction, within those constraints.
3. Current BugSmash API and MCP documentation.
4. This public agent guide.
5. Public product-content files such as `llms.txt` and `llms-full.txt`.

Tool availability, field names, scopes, limits, and workflows can change. Prefer live discovery over copied tool lists, and do not invent unsupported capabilities.