# PromptOn setup guide for coding agents

Start here with the hosted `prompton-setup` skill, then **read only the references needed for the current step and app language**. Do not load every linked page up front.

PromptOn manages prompts, model settings and immutable deployment pins outside app code. The app fetches configuration and sends monitoring logs; it calls the model provider itself with its own key and HTTP client. PromptOn is not a provider proxy.

## Launcher scope

The setup prompt's host, organization, project and prompt context is authoritative. Preserve the app host's scheme and port for CLI/API requests and browser links; do not substitute the docs host.

| Launcher | Scope |
|---|---|
| Landing | No org/project supplied. Inspect the app and authenticated targets; reuse the clear match, create only if none matches, ask if multiple legitimate targets remain. |
| Organization | Use the supplied org; reuse or idempotently create one appropriate project. |
| New project | Create a unique project in the supplied org; do not reuse an existing one. Record and reuse the returned slug on retries. |
| Existing project | Reuse the supplied org/project; configure only real server-side LLM call sites in that app. |
| Single prompt | Reuse only the supplied org/project/prompt and its call site; do not create or modify other prompts. |

## Setup sequence

1. **Inspect before writes.** Read [Setup provisioning](/setup-provisioning). Explain PromptOn briefly, identify the deployable app and server-side LLM call sites, and record prompt kind, variables, model, params, provider, tools and response parsing. If calls are absent or run only in a browser/mobile client, report the prerequisite and stop.
2. **Authenticate and scope.** Verify the CLI and use `prompton login --host <app-host> --no-browser`. Relay the actual device URL/code promptly and confirm the authenticated org/project before writes. CLI session tokens manage resources; project SDK keys read configuration and send logs. Never put either secret in chat, source control or client-side code.
3. **Provision for review.** Follow launcher scope. Read the ordered environments and select the existing **lowest active nonproduction environment**. Record its slug; export it as `PTN_SETUP_ENV`. Stop if none exists. Preserve current prompt behavior, models and params; commit typed prompt versions and deploy them to that environment. Recheck environment order before writes if it may have changed. A committed version alone is not live.
4. **Prepare samples.** Read [Setup samples](/setup-samples) now. Create exactly ten diverse successful synthetic SAMPLE logs per deployed prompt in `PTN_SETUP_ENV`, including reused prompts. These are manual fixtures, not real provider traffic. Preserve sample IDs across retries, report accepted/duplicate/rejected counts, and verify stored variables without changing retention or payload policy. Resolve failures or report incomplete setup; never claim unverified samples succeeded.
5. **Review before migration.** Read [Setup migration](/setup-migration) and use [SDK selection](/sdks) to open only the selected language's release README. Show actual prompts, deployment, Logs and Arena links; sample accounting; and the original code, proposed prompt, variable mapping, new caller and rendered comparison. Obtain app-migration approval only if it has not already been given. Missing SDK support is a prerequisite, not permission to invent methods or implement a new SDK.
6. **Migrate after approval.** Use a new app worktree and preserve provider credentials/client, behavior and return types. Keep Chat history and current input app-owned; log the final messages sent to the provider. For Decision or protocol changes, require deployed API/path/body metadata and support both old and new response contracts. Read [Tools and traces](/tools-and-traces) only if the app has tools or needs execution-trace evidence.
7. **Verify nonproduction.** Follow the migration checks and [SDK cache/bundle contract](/sdk-config-fetch). Map the app's actual production deployment-flag value to PromptOn `production`, every other value to `PTN_SETUP_ENV`; use that same environment for configuration, logs, caches and bundles. Build mode alone is not a production flag. Verify representative inputs and a real offline-cache/bundle run; report unsupported call sites separately.
8. **Hand off.** Show the diff, nonproduction verification, review links and rollback steps. Stop after setup; production rollout needs a separate request.

## Reference lookup

Use [CLI](/cli) for the command you need, [CLI HTTP API reference](/management-api) when provisioning via `/api/v1/orgs/...`, and [SDK HTTP API reference](/api) for configuration/log schemas. Read [Troubleshooting](/troubleshooting) only for a failure. These are lookup references, not a required reading list.

## Boundaries

- Do not create sample environments, reorder/delete environments, remove protection, or promote upward during setup. Preserve production pins and shared settings; do not export a production bundle or change production traffic.
- Do not infer provider endpoints from model names or silently route Decision calls to Chat. Stop the affected call site when its required deployment or request contract is unsupported.
- Use the SDK's last valid memory/disk/bundle configuration during outages. With no valid configuration, fail explicitly; never restore hard-coded prompt defaults.
- Redact secrets and private user data from logs. Keep setup fixtures distinguishable from observed provider and tool execution.

Programs can fetch this page as Markdown at `https://docs.prompton.ai/agent.md`.