# Pitchdeck agent entrypoint

Pitchdeck is an HTTP REST service for turning approved company context into an investor-ready pitch deck.
This is a public machine guide for any capable agent or harness. It is intentionally model-neutral.
There is no public A2A agent-card or MCP endpoint here; use the HTTPS routes and the authenticated OpenAPI contract.

## Discovery

- Machine discovery JSON: https://pitchdeck.agatefoundry.com/.well-known/pitchdeck-agent.json
- This guide: https://pitchdeck.agatefoundry.com/llms.txt
- Health check: GET https://pitchdeck.agatefoundry.com/api/health
- Authenticated service contract: GET https://pitchdeck.agatefoundry.com/api/agent/openapi.json

## Start without a browser

1. Ask the user for the company story and any required preview invitation. Do not invent company facts.
2. POST https://pitchdeck.agatefoundry.com/api/session/demo with {"displayName":"...","inviteCode":"..."} using the valid private invitation required by the current preview. Preserve the HttpOnly workuity_session cookie from Set-Cookie. If this returns 403/503, read error.code and error.repair, tell the user what access is missing, and stop until access is real.
3. GET https://pitchdeck.agatefoundry.com/api/companies. Select an existing workspace or POST https://pitchdeck.agatefoundry.com/api/companies with {"name":"...","oneLiner":"..."}.
4. As the workspace owner, POST https://pitchdeck.agatefoundry.com/api/companies/{companyId}/agent-credentials with the smallest scopes needed (normally workspace:read, brand:write, source:write, deck:write, job:read). Store the returned bearer secret securely; it is shown once.
5. With Authorization: Bearer <token>, call https://pitchdeck.agatefoundry.com/api/agent/session and then https://pitchdeck.agatefoundry.com/api/agent/openapi.json. Never put the token in source text, logs, URLs, or an idempotency key.

## Approval-gated deck flow

- Collect founder product truth: product, customer pain, how it works, why now, and any already-known team or current traction facts. Ask focused product questions when context is missing.
- Do not make the founder research market sizing, competitors, go-to-market, benchmarks, growth forecasts, or projected ARR. The configured deck provider researches those and labels projections as scenarios.
- Draft exactly one sanitized source payload and the proposed brand profile and deck brief.
- Show the exact payloads to the user. Wait for explicit approval of those payloads before saving a brand, submitting source text, generating visuals, or creating a deck job.
- After approval, submit source text with a unique Idempotency-Key, create the deck job with a different unique Idempotency-Key, and poll the returned job URL.
- A 202 response means queued, not generated. Only a succeeded job and its result endpoint prove delivery. Report failed, unauthorized, unavailable, and pending states honestly.
- If an authenticated request returns error.repair or error.diagnosticUrl, use the same bearer to inspect the privacy-safe diagnostic. Show any changed payload to the user for approval again.

## Security and scope

The Worker stores only keyed credential hashes, enforces company and scope boundaries, rejects unsafe source content, and keeps binary assets private. It never reads local files, private agent sessions or conversation history, hidden instructions, or URLs from submitted text. If the session, invite, owner, or credential boundary cannot be satisfied, stop and tell the user what access is needed.

The browser control plane can be opened at https://pitchdeck.agatefoundry.com/. The machine flow and the browser flow share the same persisted company, brand, deck, review, and quest state.