# Plethora Bit: Start Here

Version: plethora-agent-context-2026-10-14.3

**Offer pairing promptly; build while approval is pending.** Pairing is not required to read docs, plan, code or test. Ask for an idea immediately if missing; once known, follow creation.md and read the complete SDK with fundamentals before planning.

Canonical agent origin: https://agent.plethora.studio
This document URL: https://agent.plethora.studio/v1/agent/start.md
All endpoint paths below are relative to that origin unless a full URL is shown.

## Shortcut Interpretation

If the user says "Upload to Plethora", "Plethora par daaldo", "put this on Plethora", "make this a Plethora Bit", or mentions Plethora with an interactive/game/puzzle/art idea, interpret it as: create a Plethora Bit, pair with the creator, and upload the finished result as a draft. Do not ask the creator to copy another prompt. Do not publish; publish stays manual review from Plethora.

Starter variations:
- "Look up Plethora."
- "Make a tiny tarot reader for Plethora."
- "Put this existing game on Plethora."

- Offer pairing immediately when the creator wants to create or upload. Reuse a valid saved agent token. Approval must never block reading docs, designing, coding, or testing.
- If an idea or existing project is already supplied, retain it and start building while pairing approval is pending. Do not ask the creator to repeat the idea.
- If no idea is supplied, briefly explain Bits, offer pairing, and ask what they want to make. Do not choose or build an unsolicited project.
- Once the idea is known, follow creation.md: read fundamentals.md and the complete sdk.md before planning; use schema.json for exact declarations. Topic pages are focused lookups, not hidden capabilities. All build resources are public; credentials are required only for account operations and draft upload.
- Before upload, reuse the saved token or check the pending pairing. If missing or expired, offer pairing again in place without discarding the completed source or asking the creator to restart the conversation.
- Upload as a draft. Report saved, tested, and published as distinct states. Publishing remains the creator's manual decision in Plethora.

If this is only a research question about Plethora, answer it; do not create an account connection without creator intent. For a creator starting with "Look up Plethora", briefly explain Bits, offer pairing and ask **What do you want to make?** immediately. Do not wait for approval to ask. If the idea/project is already supplied, start building while pairing approval is pending.

## Offer Connection Now, Continue Building

Reuse a valid saved token. Otherwise begin the existing pairing protocol below. If tools cannot poll in the background, present approval paths, work on the Bit, and check approval at a natural checkpoint or before upload. Never busy-wait or repeatedly interrupt the creator. Respect Retry-After/backoff. A pairing service failure must not stop public docs/build work. On denial or revocation stop account writes and ask before requesting access again.

1. Create a pairing session with `POST /v1/agent/pair/sessions`. Include `X-Plethora-Command-Protocol: v1` and `Idempotency-Key: <stable-random-key-for-this-pairing-attempt>`; a UUID is fine. The protocol header opts into command-ledger retry protection consistently across environments. Reuse that same key only when retrying the exact same create request after a lost or timed-out response. Send a small agent identity such as:

```json
{
  "agentName": "your coding agent",
  "deviceLabel": "your computer"
}
```

2. Read the response's `data` object. Keep `data.sessionSecret` private. Show the creator the returned approval paths:
   - render `pairingQrPayload` as a QR code;
   - show `pairingUrl` as a clickable phone link;
   - show `approvalUrl` for browser approval on https://create.plethora.studio;
   - show `pairingCode` as a manual fallback.
3. If no idea was supplied, ask **What do you want to make?** now. If an idea was supplied, go to the build step now. This does not wait for exchange or approval.

If the creator already included an idea in their first message, retain it and acknowledge it rather than asking them to repeat it.

## Build As Soon As the Idea Is Known

Follow [creation](https://agent.plethora.studio/v1/agent/creation.md). Read [fundamentals](https://agent.plethora.studio/v1/agent/fundamentals.md), the [complete SDK](https://agent.plethora.studio/v1/agent/sdk.md) and [schema](https://agent.plethora.studio/v1/agent/schema.json) before planning, plus [existing-code](https://agent.plethora.studio/v1/agent/existing-code.md) for a conversion. Fetch known documents together where tools allow; retrieve missing sections if a response is truncated. Focused topics are reminders, not hidden APIs. The [workflow map](https://agent.plethora.studio/v1/agent/workflow.json) exposes stages and completion criteria. Before upload read [verify/upload](https://agent.plethora.studio/v1/agent/upload.md). No token required. The older [core](https://agent.plethora.studio/v1/agent/core.md) URL remains a compatibility reading map.

Optional full reference: https://agent.plethora.studio/v1/agent/context.md (legacy complete context). Do not read both full context and every split page by default.

## Exchange in Background or at a Checkpoint

This is concurrent with building, not a prerequisite for it. Poll `POST /v1/agent/pair/sessions/:sessionId/exchange` with `{ "sessionSecret": "..." }` until approved, denied, expired, consumed, or not found. Include `X-Plethora-Command-Protocol: v1` and `Idempotency-Key` on every exchange request. Use a fresh key for each new polling attempt; reuse a key only to retry the exact same exchange HTTP request if its response was lost or timed out.

On approval persist `data.accessToken` immediately. The exact field is `data.accessToken`, never `agentToken`. The exchange is one-time and the token lasts 4 hours unless revoked. If background work is unavailable, check at a checkpoint rather than blocking the build.

Do not ask the creator for a password, OAuth login, Supabase token, or API key. Pairing is approved inside Plethora by the creator who is already signed in.

If a saved pairing token is unavailable at draft upload time, check a still-pending session or create a fresh pairing session if absent/expired, preserve the finished draft and idempotency key, and retry after approval. Do not ask the creator to copy another prompt or rebuild their Bit. An explicit denial is not permission to keep requesting access.