# VoteShip Agent Instructions

VoteShip is an agent-accessible feature request management platform. Use it to collect product feedback, turn unstructured requests into organized backlog items, understand customer demand, plan roadmap work, and publish shipped changes.

## When to use VoteShip

Reach for VoteShip when the user asks you to:

- submit a feature request or product suggestion to a VoteShip board;
- browse an existing feedback board, find similar requests, vote, or add a public comment;
- turn feedback from email, chat, calls, support tickets, or research notes into structured product requests;
- detect duplicate ideas, categorize an inbox, summarize themes, or assess sentiment;
- prioritize features using vote counts, customer value, revenue, effort, or roadmap status;
- plan a sprint from approved feedback or move requests through the product lifecycle;
- create, update, or publish a roadmap, changelog entry, or release;
- connect a feedback widget, webhook, API client, CI workflow, or MCP-compatible agent to VoteShip.

Do not use VoteShip as a replacement for incident response, general customer support ticketing, source-control issue tracking, or storage of passwords, API secrets, payment details, or other sensitive data. Ask for human confirmation before deleting posts, comments, tags, releases, or integrations.

## Choose an interface

### MCP server

Use MCP when the host supports Model Context Protocol and the agent needs discoverable, typed tools.

For a hosted connection, use the Streamable HTTP endpoint. It exposes public
board tools without credentials:

```bash
# Claude Code
claude mcp add --transport http --scope user voteship https://voteship.app/mcp

# Codex
codex mcp add voteship --url https://voteship.app/mcp
```

For project administration, send the project's VoteShip secret as
`Authorization: Bearer sk_...`. If the host cannot securely attach that header,
use the local package configuration below so the secret remains in the MCP host
environment.

```json
{
  "mcpServers": {
    "voteship": {
      "command": "npx",
      "args": ["-y", "@voteship/mcp-server"],
      "env": {
        "VOTESHIP_PROJECT_SLUG": "your-public-board-slug"
      }
    }
  }
}
```

Public mode does not require an API key. Set `VOTESHIP_API_KEY=sk_...` only for authenticated project administration, and never expose that secret in client-side code or conversation output.

### Website installer

Use the VoteShip CLI when the user asks you to add a feedback widget to a site.
It detects the root layout or HTML entry file, makes an idempotent edit, and can
verify the deployed HTML.

```bash
npx -y @voteship/cli init --project-key pk_your_public_key
npx -y @voteship/cli verify --url https://your-site.example
```

Use the `pk_` public key only. Never place the project's `sk_` secret in a
browser bundle or widget attribute. Use `--dry-run` when the target file is
ambiguous and `--force` only after confirming an existing VoteShip widget should
be updated.

### REST API

Use the REST API for server-to-server integrations, generated clients, batch workflows, and environments without MCP. Discover endpoints at `https://voteship.app/api/v1/` and fetch the OpenAPI 3.1 document at `https://voteship.app/api/v1/openapi.json`. Authenticated requests use `Authorization: Bearer sk_...`.

### Public API

Use public endpoints for end-user actions on a known public board. A new submission is created as `PENDING` so the board owner can review it. Search or browse before submitting when duplicate requests would reduce signal quality.

## Operating guidance

1. Identify the target project or public board slug before writing data.
2. Browse or search for an existing request before creating a new one.
3. Preserve the user's wording and source context; do not invent customer evidence, revenue, votes, or status.
4. Prefer reversible updates. Confirm destructive actions and explain their scope.
5. Treat `401` as a credential/configuration issue, `403` as a permission or plan issue, `409` as a conflict, and `429` as a signal to wait for `Retry-After`.
6. After a write, report the returned identifier, status, and any next approval step.

## Developer resources

- VoteShip Developer Hub: https://voteship.app/developers
- VoteShip API documentation: https://voteship.app/docs
- VoteShip OpenAPI 3.1 specification: https://voteship.app/api/v1/openapi.json
- VoteShip MCP discovery: https://voteship.app/.well-known/mcp.json
- VoteShip remote MCP endpoint: https://voteship.app/mcp
- VoteShip API catalog: https://voteship.app/.well-known/api-catalog
- VoteShip pricing summary: https://voteship.app/pricing.md
- VoteShip authentication guide: https://voteship.app/docs#authentication
- VoteShip webhook guide: https://voteship.app/docs#webhooks
- VoteShip concise agent index: https://voteship.app/llms.txt
- VoteShip complete agent reference: https://voteship.app/llms-full.txt
- VoteShip website installer: https://www.npmjs.com/package/@voteship/cli
- VoteShip security contact: https://voteship.app/.well-known/security.txt