# How Clanker Ship works

The website, the API and the MCP server run the same services, with the same permission checks behind each.

Clanker Ship has one set of services: the rules for workspaces, planning, agent messages, test runs
and secrets, and the permission checks that guard them. The website, the HTTP API and the MCP server
are three ways to call those services. An action that a viewer may not take is refused on all three,
with the same message.

## The surfaces

| Surface        | Address                                 | Who uses it                                     | Signs in with                      |
| -------------- | --------------------------------------- | ----------------------------------------------- | ---------------------------------- |
| Website        | `https://clankertest.com`               | People                                          | Google, or email and password      |
| HTTP API       | `https://api.clankertest.com/v1`        | Scripts, CI, integrations and the `clanker` CLI | API keys, or the CLI's own sign-in |
| MCP server     | `https://api.clankertest.com/agent/mcp` | Coding agents                                   | An agent grant, through OAuth      |
| Agent HTTP API | `https://api.clankertest.com/agent/v1`  | The plugin's CLI, and agents without MCP        | The same agent grant               |

The website calls the services directly, not through the API. The API and the MCP server run
together on the API host and call the same services for each request. A background worker sends
invite emails and runs scheduled jobs with the same services. Workspace data lives in one database,
and test-run evidence such as videos and traces is kept in object storage.

## Who acts

Every request acts for someone, and the services check that someone's role in the workspace before
they read or change anything.

| Caller             | Credential                          | Acts with                                                                   |
| ------------------ | ----------------------------------- | --------------------------------------------------------------------------- |
| A person           | A website session                   | Their role in the workspace                                                 |
| A user API key     | `ctk_…`                             | Its owner's current role in each workspace                                  |
| A CLI login        | `ctat_…`, from `clanker auth login` | The person who signed in                                                    |
| An account API key | `ctk_…`, belonging to one workspace | The role it was given: owner, admin, member or viewer                       |
| An agent           | An access token from its grant      | The person who granted it, limited to the grant's `read` and `write` scopes |
| A vault key        | `ctvk_…`                            | Nothing but pulling the production secrets it names                         |

Roles are owner, admin, member and viewer; see
[Workspaces and roles](https://docs.qa.clankership.net/get-started/concepts/workspaces-and-roles.md). An agent never has more access
than its person: a viewer's agent only reads.

## One rule set

Because every surface calls the same services:

- **The rules match.** A slug that is taken, an archived product, or a ticket status from another
  team fails the same way on the website, through the API and from an agent. The API returns it as
  an [error](https://docs.qa.clankership.net/api/errors.md) with a tagged name; the MCP server returns it as a tool error with a code.
- **The operations match.** The API does everything the website does. Each MCP tool has an HTTP
  twin under `/agent/v1`, so the plugin's CLI and the MCP server cannot drift apart.
- **Workspaces stay apart.** Another workspace's objects are not found: requests for them return
  `404`, never `403`.

## Every change is recorded

Each change writes an event in the same transaction, naming what changed and who changed it: the
person, the agent and the person it works for, or the account API key. The workspace's
**Events** page lists them, and so does [List events](https://docs.qa.clankership.net/api/events/list.md).

## The loop

Clanker Ship is built around one loop. People decide what to build and accept the proof; agents do
the work in between.

1. A person or an agent creates a ticket on a team, such as `WEB-31` Add docs search.
2. A person sends the ticket to their agent with an ask, such as Write the plan.
3. The agent writes the plan from the team's
   [agent instructions](https://docs.qa.clankership.net/get-started/concepts/planning/agent-instructions.md) and saves it on the
   ticket.
4. The agent builds it and runs the tests with `clanker run`, which publishes a
   [test run](https://docs.qa.clankership.net/get-started/concepts/test-runs.md) with every test's evidence.
5. The person reviews the run and moves the ticket to Done.

Pull requests are the next part of the loop to arrive in Clanker Ship.