# KonfigurátorSPZ agent guide

Canonical guide: https://spz-gen-pr61.dokploy.martinmachava.com/developers/agent.md

## Choose the narrowest integration

1. For a person to inspect a design, build https://spz-gen-pr61.dokploy.martinmachava.com/?text={URL_ENCODED_TEXT}&type={type}. Percent-encode the text as one query value and use one type from standard, carrier, truck, van-square, square, motorbike, moped.
2. For structured rule evaluation, advisory availability, or PNG generation, use the REST API at https://spz-gen-pr61.dokploy.martinmachava.com/api/v1.
3. For an anonymous browser preview, use the copy/paste HTML or public hosted SDK examples at https://spz-gen-pr61.dokploy.martinmachava.com/developers/docs/embeds; no session is required. For registered metered calls, create an origin-bound browser session from your trusted server. Install @konfigurator-spz/sdk from https://spz-gen-pr61.dokploy.martinmachava.com/developers/sdk/konfigurator-spz-sdk-0.1.0.tgz, not the npm registry.
4. For autonomous evaluation, use the onboarding paths below directly or call the tools at POST https://spz-gen-pr61.dokploy.martinmachava.com/mcp.

## Current REST paths

- POST https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/plates/generate accepts a shape, renderable text, optional colors, and optional branding. It creates an asynchronous operation.
- POST https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/plates/verify evaluates rules without reserving a mark.
- POST https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/plates/availability accepts legally valid official text and checks a dated registry snapshot.
- POST https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/browser-sessions is server-only and creates a bounded session for an exact allowed browser origin.
- GET https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/pricing is public. GET https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/usage is authenticated.
- GET https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/operations/{id} polls an owned operation. GET https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/artifacts/{id} retrieves an owned artifact.

Use the schema at https://spz-gen-pr61.dokploy.martinmachava.com/openapi.json. Send billable POST requests with a stable idempotency key. Retry a transport failure with the same key, honor Retry-After, and keep one operation poll in flight. Authentication and ownership failures deliberately do not reveal another tenant's resource.

## Autonomous evaluation, domain, and claim paths

- POST https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/agent-trials requires an empty JSON object and a stable Idempotency-Key. It returns 201 for the first issuance and 200 for an idempotent replay; apiKey is returned only once and secretReturned reports whether it is present.
- POST https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/agent-trials/domain-challenges accepts only hostname and requires a server credential in the Authorization: Bearer header.
- GET https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/agent-trials/domain-challenges/{challengeId} reads an owned challenge.
- POST https://spz-gen-pr61.dokploy.martinmachava.com/api/v1/agent-trials/domain-challenges/{challengeId}/verify accepts an empty JSON object and performs bounded HTTPS verification.
- Human handoff at https://spz-gen-pr61.dokploy.martinmachava.com/developers/claim/{claimHandle}

The evaluation policy is narrow: a trial is short-lived, attributed to KonfigurátorSPZ.cz, tightly metered, and limited in scope. It cannot purchase credits, accept human legal terms, or establish durable ownership. Anonymous evaluation does not verify identity. A promotion requires an issued HTTPS challenge at the exact /.well-known/konfiguratorspz.json path. Durable claim requires an existing authenticated Clerk principal and current acceptance, directly or through explicitly authorized delegation; claim rotates or revokes pre-claim credentials.

## Safety and legal boundaries

- Treat verification and availability as advisory. Neither reserves a mark nor replaces a decision by the competent Czech authority.
- Keep credentials out of URLs, client source, logs, cookies, analytics, and postMessage.
- Preserve required visible provider attribution on provider-branded or fallback output.
- Do not submit personal, confidential, unlawful, or third-party credential data for evaluation.
- Review https://spz-gen-pr61.dokploy.martinmachava.com/developers/terms and https://spz-gen-pr61.dokploy.martinmachava.com/developers/privacy before integration.

OpenAPI service description: https://spz-gen-pr61.dokploy.martinmachava.com/openapi.json
Reusable instructions: https://spz-gen-pr61.dokploy.martinmachava.com/developers/SKILL.md

Anonymous trial scopes are exactly generate, verify and artifacts; owned operation polling is allowed. Anonymous trial credentials cannot call availability, usage or browser-session issuance, accept customer terms, purchase credits or establish durable ownership. Read returned credits/scopes/expiresAt. A serviceMode of paid can consume evaluation credits; it is not evidence of a payment. If issuance is ambiguous, retain the original idempotency key and use authenticated owner/operator recovery, not another trial to evade limits.

The public iframe is a separate anonymous provider-attributed preview, not a debit to a developer wallet or a private artifact contract. It may put non-sensitive text in publicly cached image URLs; private authenticated artifacts are no-store. For the complete server generate/verify/availability → poll → artifact recipe, see https://spz-gen-pr61.dokploy.martinmachava.com/developers/docs/getting-started. For copy-ready HTML, React, vanilla and configuration/theme examples, see https://spz-gen-pr61.dokploy.martinmachava.com/developers/docs/embeds.

SDK 0.1.0 is distributed as https://spz-gen-pr61.dokploy.martinmachava.com/developers/sdk/konfigurator-spz-sdk-0.1.0.tgz, not from the public npm registry. In your own application directory, install the HTTPS tarball with npm install, following https://spz-gen-pr61.dokploy.martinmachava.com/developers/docs/embeds#install-the-public-sdk-tarball. No repository checkout is required.

Production rollout remains on hold pending operator release confirmation, provider readiness and measured capacity. A preview artifact, current published terms/privacy notice or provisional CZK pricing is not production activation. The legal documents are current published documents, not draft placeholders. Confirm commercial rollout with info@konfiguratorspz.cz.


## MCP request envelope (read-only discovery)

MCP protocol revisions and the JSON-RPC envelope version are different fields. Both supported MCP revisions (2026-07-28 and 2025-06-18) require the exact string "jsonrpc":"2.0"; "2" is not a modern alternate spelling.

For 2026-07-28, each request is independent: send MCP-Protocol-Version, MCP-Method, MCP-Name for tools/call, and matching per-request protocol/client-capabilities _meta. There is no initialize or session prerequisite. This read-only tools/list call creates no trial and needs no credential:

```sh
curl --fail-with-body 'https://spz-gen-pr61.dokploy.martinmachava.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'MCP-Method: tools/list' \
  --data '{"jsonrpc":"2.0","id":"list-1","method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'
```

For a read-only tools/call, use describe_integration with arguments {} and add MCP-Name: describe_integration plus MCP-Method: tools/call; retain the same per-request _meta. Never issue a trial merely to test an envelope.

For legacy 2025-06-18, initialize first, retain the returned MCP-Session-Id, send notifications/initialized, and include both session and protocol-version headers on subsequent calls. Both modes require Content-Type: application/json and Accept: application/json, text/event-stream. Authentication for protected tools is an HTTP Bearer header, never JSON-RPC arguments. Use only Streamable HTTP, not deprecated HTTP+SSE.


## Accountable delegated acceptance and claim (REST)

An anonymous evaluation principal cannot accept terms, bind a customer, purchase credits, or claim accountable ownership. Domain control is not identity. An existing authenticated Clerk account owner/admin may explicitly delegate bounded acts; the agent is not recorded as that human.

1. Create a trial and retain its trialId and separate claim bearer securely. The legacy claimUrl contains the bearer as its last path segment; extract it locally and do not navigate to or log it for the delegated flow.
2. The accountable owner authorizes once at /developers/agents or through GET/POST /api/v1/agent-authority/authorizations using the existing Clerk session. GET returns the active account, principalUserId, CSRF token, exact authorization statements and recent authorizations. POST requires same-origin Origin, X-CSRF-Token, a stable Idempotency-Key for grant issuance, Content-Type application/json, and the complete JSON body below. Replace placeholders with the exact management GET values; do not submit placeholders. Owner identity and account come from the session, never input names or claimed identities. This grants no purchase authority. The response body returns capability once. No page-click acceptance is required for subsequent delegated acts.
3. GET /api/v1/agent-authority/terms returns canonicalDocumentVersion, version, sections, documentSha256, canonicalization, and delegateAttestation. Verify SHA-256 over UTF-8 JSON.stringify({version:canonicalDocumentVersion,sections}) yourself. Read the exact document before acceptance.
4. POST /api/v1/agent-authority/accept with only {capability,termsVersion:version,documentSha256,attestation:delegateAttestation}. This is an explicit delegated act on behalf of the named principal, not a claim to have performed a human click. The exact authorized version/hash is required. A changed document requires new owner authorization.
5. POST /api/v1/agent-authority/claim with only {capability,claimSecret}. Both the capability (bound to that exact trial) and separate claim bearer are required. Claim preserves trial account/project/ledger identity, attaches the accountable principal as owner, revokes all preclaim keys and browser sessions, and returns the rotated API key in the response body once.
6. Operation spending is NOT implied by claim. By default the returned key has only artifacts and usage:read and a zero monthly project credit budget. To authorize operation calls, explicitly include operationScopes (generate, verify, availability), monthlyCreditBudget (0–10000), and spendingAuthorization (exact statement from management GET) when issuing authority. These scopes do not include browser-session issuance. The rotated operation key expires with authority (maximum one hour), revocation also revokes it, and the existing project monthly spend guard meters queued/running/succeeded operation credits. The budget is monthly, not a lifetime allowance; no credit purchases or checkout permissions are granted.
7. Revoke using authenticated POST /api/v1/agent-authority/authorizations with {intent:"revoke",authorityId}, Origin and X-CSRF-Token. GET lists the latest 100 of this principal's active-account authorizations without secrets. Completed ownership and legal evidence remain; revocation prevents future use, not retroactive erasure.

Owner management POST body (valid JSON with explicit placeholders, no operation-spending grant):

```json
{
  "intent": "issue",
  "authorization": {
    "trialId": "<trialId from the retained trial response>",
    "agentName": "Owner-approved deployment agent",
    "scopes": [
      "terms:accept",
      "trial:claim"
    ],
    "expiresInSeconds": 900,
    "termsVersion": "<termsVersion from management GET>",
    "documentSha256": "<documentSha256 from management GET>",
    "authorization": "<exact authorization statement from management GET>"
  }
}
```

Never infer customer consent from a successful evaluation, domain proof, or contractor assignment. The authenticated owner must review and authorize these exact acts first. Use /developers/agents for the interactive owner flow. The example intentionally omits operationScopes, monthlyCreditBudget and spendingAuthorization; adding operation spending requires a separate explicit owner decision and the exact management statement.

Capability and rotated key are body-only one-time responses. Never put capability or claimSecret in a URL, logs, analytics or a cookie. Delegated endpoints reject every query parameter. Grant issuance retries with the same Idempotency-Key return the same record without capability; changed payloads conflict. Acceptance/claim are single-use transactions: concurrent/repeated requests return 409 after the successful act and never repeat secrets or duplicate legal evidence. If a response is lost, the authenticated owner can inspect state; issue a fresh key through existing owner controls rather than replaying a secret. Expired/revoked, wrong-scope, wrong-account/member/role, wrong-trial/bearer, stale-version/hash, and anonymous requests fail closed. Delegated acts retain immutable authorization and acceptance/claim evidence with accountable principal, agent label, scope/budget, account, exact terms/hash, attestation and timestamps. An agent label is an owner-provided label, not independently verified software identity.