# 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.

```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.

### 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 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