# Clanker Test docs for agents

Read /llms.txt for the index and /AGENTS.md for operating rules. The public API is the source of truth for HTTP operations. The web UI uses the same Effect services directly and must not be used as the HTTP contract.

## Overview

Clanker Test is a workspace where people and coding agents share the same product actions. Permission checks live in @clanker-test/services.

## Architecture

- apps/web: UI + cookie auth + OAuth consent. Calls services in-process. Never HTTP-calls the public API.
- apps/api: /v1 HTTP, MCP, OAuth token/register, well-known. Deployable Cloudflare Worker.
- apps/worker: queue consumer + cron. Deployable Cloudflare Worker. Uses the same services.
- apps/docs: TanStack Start docs website. Guides, OpenAPI, llms.txt. Deployable Cloudflare Worker.
- packages/services: Effect.Service domain layer, worker runtime, public HttpApi (`toWebHandler`), MCP.
- packages/db: product Postgres schema (clanker_test)
- packages/admin-db: admin Postgres schema (clanker_test_admin)

## Authentication

API: hashed user API key as Authorization: Bearer ctk_… or X-API-Key. Create keys on the website Security settings.
Prefix: /v1 on the API origin (localhost :3200, api.qa.clankertest.net, api.clankertest.com)
Agents: OAuth against API resource {API_URL}/agent/mcp
Consent UI: website /agent/oauth/authorize

## Public API

See /openapi.json. Notable groups:

- API keys: GET/POST /v1/api-keys, POST /v1/api-keys/{id}/revoke
- Profile: /v1/me, /v1/me/photo, /v1/me/preferences, /v1/me/home, /v1/me/onboarding
- Workspaces: /v1/workspaces, /v1/workspaces/{slug}, icon, members, invites, teams, events, people, seeds, integrations, slug-availability
- Slugs: GET /v1/slugs/{slug}
- Invites: GET /v1/invites/{token}, POST /v1/invites/{token}/accept

## Agents

MCP tool read_validation_kit. HTTP POST /agent/v1/validation-kit:read
Register: POST /agent/oauth/register
Token: POST /agent/oauth/token
Discovery: GET /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource on the API origin.