Audience: developers integrating PromptLab into a product, prompt
engineers iterating on prompt quality, and any teammate who needs to
ship a working prompt without becoming a model expert first.

What you'll be able to do at the end:

• Compose a working prompt from scratch — even if you've never written
  one before — using the Lab Assistant.
• Run that prompt against multiple models side-by-side, compare
  outputs, and pick a winner with confidence.
• Iterate on the prompt with surgical edits (Refine), full rewrites
  for a specific model (Optimize), or cross-model rewrites
  (Optimize-for-cohort).
• Save it as a versioned prompt, retrieve old versions, roll back if
  needed.
• Call the prompt from your own code via the SDK or HTTP API.
• Track cost, latency, and quality over time; spot regressions before
  your customers do.

---

Each section is self-contained — skim the table of contents and jump
to what you need. Hands-on steps are numbered. 📸 Screenshot call-
outs flag the moments where a captured image best explains what the
UI is doing; the surrounding paragraph describes the exact framing
to capture.

---

1. What is PromptLab?
2. First-time setup
3. Your first prompt — Compose with AI
4. Running prompts: the Prompt Studio
5. Saving and versioning
6. Iterating with the Lab Assistant
7. Scenarios — capture every iteration
8. Eval rules — automated quality checks
9. Cost analytics and cache savings
10. Calling prompts from your code
11. Providers, models, and BYO keys
12. Interactions explorer — debug like a pro
13. Common workflows / cheat sheet

---

PromptLab is a prompt registry + multi-provider router in one.

• The registry is where your prompts live — versioned, scoped to
  a project, retrievable by name from your code.
• The router is the execution engine that takes a prompt + a
  model + inputs and returns a response, regardless of which provider
  the model belongs to.
• The Lab Assistant is PromptLab's own AI helper — it writes,
  optimises, and explains prompts on your behalf, so you're never
  staring at an empty editor.

You'll see all three integrate seamlessly. You write a prompt once
(or have the Lab Assistant write it for you), test it against any
model your project has access to, save the version that works, then
call it from production by name — your code never references a
specific model identifier or a vendor SDK.

📸 Screenshot 1 — Hero shot
Capture: the Prompt Studio main view with a populated prompt, three
or four model cards visible in the cohort, results panel showing
side-by-side responses, and the Save / Run buttons in the bottom
bar. This is the "this is what PromptLab looks like in motion" image
for the top of the tutorial.

---

2.1 Sign in

Browse to https://promptlab.vernalabs.net and sign in. PromptLab
supports email/password, Google, and Microsoft.

📸 Screenshot 2 — Sign-in page
Capture: the sign-in screen with the three auth options visible.
Crop to just the auth panel; no need to show the surrounding browser
chrome.

2.2 Create a project (or pick one)

Projects are the unit of isolation in PromptLab — each has its own
prompts, its own provider keys, its own cost analytics, its own API
keys. A typical setup is one PromptLab project per real product (one
per app or per team).

1. Top bar → Active project dropdown → + Create project.
2. Give it a short slug-friendly name (lowercase, hyphens — used in
   URLs and API calls). Display name can be anything.
3. Click Create.

📸 Screenshot 3 — Create-project dialog
Capture: the create-project modal open over a dimmed background,
form fields filled in with a believable example name like
acme-marketing.

2.3 Configure a provider account

Before you can run anything you need a model, and before you can
have a model you need a provider account — a stored credential
for OpenAI, Anthropic, Google, OpenRouter, FAL, Replicate, etc.

1. Sidebar → Providers.
2. Click + Add account.
3. Pick the provider type, paste the API key, give it a label,
   Save.

The fastest path to having access to "every model in the market" is
OpenRouter — one key, one balance, hundreds of models behind it.
Direct provider keys (OpenAI, Anthropic, Google) give you native
discounts (Anthropic prompt caching, OpenAI Batch API 50%-off, etc.)
when you outgrow the openrouter convenience.

📸 Screenshot 4 — Providers page with a couple of accounts
Capture: the Providers list showing 2-3 configured provider
accounts (OpenAI, Anthropic, OpenRouter), each with the green
"active" status and the Provider Health column visible.

2.4 Pick which models to expose

By default PromptLab knows about every model your providers offer
but doesn't expose all of them in the UI. Go to Project Settings
→ Models to pin the models you want available in Prompt Studio.

1. Sidebar → Models.
2. Filter by provider, modality, capability.
3. Toggle the In project switch on each model you want.

This is also where you set per-model mediaFieldMap if you're
working with image / video providers (see "Power moves" later).

📸 Screenshot 5 — Models page with filters in use
Capture: the Models page with a few filter pills active (e.g.
"Text" + "Anthropic" or "Image generation"), showing 5-10 rows
filtered down. The "In project" toggles should be visible on the
right side of each row, with a mix of on/off so the toggle action
reads clearly.

---

You don't write your first prompt by typing into an empty box. You
describe what you want in plain English and let the Lab
Assistant draft a working prompt for you, in the syntax of the
target model.

3.1 Open Prompt Studio

Sidebar → Prompt Studio. The studio has three areas:

• Top: model cohort selector — which models to run against.
• Middle: prompt editor.
• Bottom: results panel — one card per model, populated after
  Run.

3.2 Click "✨ Compose with AI"

The button sits in the top-right of the editor toolbar, next to
Copy. It pulses gently when the editor is empty.

📸 Screenshot 6 — The Compose with AI button highlighted
Capture: zoom into the editor toolbar showing the "✨ Compose with
AI" button, with the empty-editor placeholder text visible
underneath. Add a small red rectangle/arrow annotation pointing at
the button (use Skitch or your preferred tool).

3.3 Fill the Compose form

A side sheet opens. Fill it in with what you want:

• Task description — plain English: "Summarise a news article
  in 3-5 bullet points highlighting the most important facts."
• Output format — Text / JSON / Markdown.
• Output schema (optional) — if you picked JSON, paste an
  example shape. The assistant will enforce it in the prompt.
• Constraints (optional) — tone, length cap, refusal rules.
  "Bullet points must each fit on one line. No emojis."
• Example pairs (optional but powerful) — give 1-3 input/output
  pairs so the assistant learns your style.
• Target models — auto-populated from the current cohort.

Click Generate.

📸 Screenshot 7 — Compose form filled in
Capture: the Compose side sheet with all fields filled with the
"news article summariser" example. Show the multi-model target
selector at the bottom with at least Claude + GPT + Gemini ticked.

3.4 Review the per-model variants

The result tab strip shows one prompt per target model, each in
that model's native syntax:

• Claude → XML tags (<task>, <context>, <output_format>).
• GPT-4 → structured chat (system message + user message + JSON
  schema).
• Gemini → markdown sections + numbered lists.

For each variant you see the prompt text, a one-line rationale
("Used XML for Claude — strongest at structured tags"), and three
actions:

• Use this prompt — replaces the editor content.
• Use as new variant — adds a separate Claude-syntax editor tab
  next to the existing prompt.
• Regenerate with a refinement note ("make the tone more
  technical").

📸 Screenshot 8 — Per-model variants in the Compose result
Capture: the result view of the Compose sheet showing the tab strip
("claude-sonnet-4.5" / "gpt-4o" / "gemini-2.5") and the body of one
tab — the XML version is the most visually distinctive, capture
that one. Show the three action buttons at the bottom.

3.5 Apply

Click Use this prompt on the Claude tab. The sheet closes; an
inline pill above the editor reads "✨ Drafted by Lab Assistant —
edit freely" with a thumbs-up / thumbs-down pair (this is how the
assistant learns from your taste — please rate generously).

📸 Screenshot 9 — Editor populated with the drafted prompt
Capture: the editor area with the drafted XML prompt visible, the
purple pill at the top reading "✨ Drafted by Lab Assistant — edit
freely" with the thumbs-up / thumbs-down pair on the right.
Annotate the pill with a small arrow + caption "Lab Assistant
attribution + rating controls".

---

4.1 The model cohort

The model row at the top is your cohort — every model selected here
runs in parallel when you click Run All. Filter by provider,
modality, and capability using the pills at the top.

Modality cohort lock — once a model is selected, all models
with a different declared modality (text / image / video / audio /
music) become unselectable until you clear the cohort. This
prevents accidentally putting a "summarise this article" prompt
against an image model — the cohort gets locked to one modality.

📸 Screenshot 10 — Modality cohort lock in action
Capture: the top model strip with one text model already selected,
some image models visible but greyed out, and the lock caption
"Cohort locked to text — clear to compare across modalities" in the
header banner. Show the "X clear cohort" link.

4.2 Enter inputs

If your prompt has placeholders ({{articleText}},
{{tone}}), input fields appear below the prompt editor — one per
placeholder. PromptLab auto-detects placeholders in both
double-brace {{name}} and single-brace {name} syntax.

Tip: once you fill an input it persists across runs in the same
session. Clearing the prompt clears the inputs.

📸 Screenshot 11 — Inputs panel with placeholders detected
Capture: the prompt editor with placeholders visible ({{articleText}})
and the inputs panel below showing a multi-line textarea filled
with a real article. The "Detected placeholders: articleText"
badge should be visible.

4.3 Run

Click Run All. Each model card in the bottom panel populates
in parallel — typical text generations finish in 2-5 seconds.

Each result card shows:

• The model name + provider.
• Cost (e.g. $0.0042) and tokens used.
• Latency (e.g. 1,840 ms).
• The output text or asset preview (image / video / audio).
• Eval rule pass/fail badges if you've set rules.
• Three action icons: Explain this run, Open in interaction
  detail, Copy output.

📸 Screenshot 12 — Side-by-side results across 3 models
Capture: the results panel populated with 3 model cards showing
their respective outputs side by side. Pick a prompt where the
outputs visibly differ (length, structure) so the comparison reads
clearly. Show the cost / latency / token-count footer on at least
one card.

4.4 Cancel a slow run

Long media generations (video, music) can run 30-60 seconds. The
Cancel All button replaces Run All while a run is in
progress; the Cancel icon on each card lets you cancel one
model without aborting the others.

---

5.1 Save Prompt vs Save new version

After you've validated a prompt with at least one Run All, click
Save Prompt (bottom bar). The dialog has two modes:

• New prompt — creates a brand-new prompt record. You'll set
  a promptId (slug, immutable, used in API calls), display name,
  intent, tags, default model, fallback models, output template.
• Save new version of <X> — only available when you arrived
  at Prompt Studio with ?promptId=... in the URL or by clicking
  Open in Prompt Studio from an interaction. Reuses the source
  prompt's identity and just creates a new version with the
  current editor content.

The dialog auto-defaults to whichever mode is appropriate, with a
toggle at the top to switch.

📸 Screenshot 13 — Save dialog in "Save new version" mode
Capture: the Save Prompt dialog open in newVersion mode, showing
the toggle pills at the top ("Save new version of acme-summariser"
selected, "New prompt" deselected), the prompt-text preview, and
the changelog field. The mode toggle is the key UX point.

5.2 ✨ Suggest name / Suggest tags

Both the New-prompt mode of the dialog have Suggest name and
Suggest tags pills above the input fields (only when the Lab
Assistant is reachable). Click them to have the assistant read the
prompt template and propose a fitting name + tags.

📸 Screenshot 14 — Suggest pills in the Save dialog
Capture: zoomed crop of the Name and Tags rows in the New-prompt
mode of the Save dialog, with the "✨ Suggest name" and "✨ Suggest
tags" pills visible above each input. Show one of the inputs
already populated by the suggestion (so the user sees the result,
not just the trigger).

5.3 Version list

Sidebar → Prompts → click any prompt → Versions tab. Every
version is here with its activation status, changelog, creator,
and a Use this version action that opens it in Prompt Studio.

📸 Screenshot 15 — Versions list
Capture: a prompt's versions tab with 4-5 versions visible in
chronological order, the active version (v3) highlighted in green,
each row showing the changelog snippet and the creator. Show the
"Activate" / "Use this version" actions on a non-active row.

5.4 Activate / rollback

Activating a version makes it the default returned by the SDK
when no explicit version param is passed. The previous active
version stays in history forever — rollback is one click.

---

This is where PromptLab earns its name. Five surfaces, layered
from passive helper to active rewriter. Every output is badged
"✨ Generated by Lab Assistant" so AI suggestions never get
mistaken for teammate edits, and every surface offers thumbs-up /
thumbs-down rating that becomes training signal for future
improvements.

6.1 Optimize — full rewrite for a target model

When to use: the prompt works but you want the strongest
possible version for a specific model (e.g. you've decided to ship
on Claude Sonnet 4.5 and want it tuned for Claude's strengths).

1. Click the floating Optimize button (bottom-right of the
   editor when there's content + at least one prior interaction).
2. Side sheet opens, split vertically: current prompt on the left
   (read-only), controls on the right.
3. Set Mode to Optimize for one model.
4. Pick the Target model.
5. Pick Optimize for weights — Accuracy / Cost / Latency /
   Brevity / Faithfulness (chips, multi-select).
6. Pick Baseline scope — last N runs / last week / specific
   scenario.
7. Click Generate suggestions.

Result view shows:

• Diff of original vs suggested (color-coded green/red).
• Per-rule projected delta ("Accuracy +12%, Cost −8%").
• Collapsible "Why this works" rationale.
• Three actions: Apply all, Apply selected hunks, Discard.

📸 Screenshot 16 — Optimize sheet result view
Capture: the Optimize side sheet open, with the diff visible
(green-and-red lines), the projected-delta chips at the top
("Accuracy +12%, Cost −8%"), the "Why this works" rationale
expanded, and the three apply/discard buttons at the bottom.

6.2 Optimize for cohort — one prompt that runs cleanly across providers

When to use: you're running a comparison batch across Claude

• GPT + Gemini and want the prompt to be a fair test — no
  Claude-leaning XML, no GPT-leaning JSON-schema, just a
  provider-agnostic prompt that all three can interpret reasonably.

1. In the Optimize sheet, switch Mode to Optimize for
   cohort.
2. The target-model dropdown disappears; the current cohort is
   used.
3. Generate suggestions returns one unified prompt + optional
   perModelNotes[] that warn you about model-specific
   interpretations to watch for.

📸 Screenshot 17 — Optimize-for-cohort result with perModelNotes
Capture: the Optimize sheet in cohort mode, showing the unified
prompt diff and the perModelNotes panel at the bottom with one
note per cohort model ("Claude may be too verbose unless capped",
"GPT will follow the schema strictly", etc.).

6.3 Refine — surgical amendment

When to use: the prompt is 95% right, you just need to fix
one specific thing. "Still missing the article date in the
output." / "The SEO keywords aren't well incorporated."

1. Optimize sheet → Mode → Refine.
2. Type the issue into What needs to change as a free-form
   note.
3. Generate suggestion returns the smallest possible edit
   that addresses the note, preserving everything else.

The diff is usually a few lines added or rephrased, not a full
rewrite. Use this for nitpicks instead of full Optimize when
you're afraid the assistant will throw out something you like.

📸 Screenshot 18 — Refine mode
Capture: the Optimize sheet in Refine mode, the "What needs to
change" textarea filled with a real note, and the result diff
showing 2-3 line changes only (in contrast to the full-rewrite
diff in earlier screenshots).

6.4 Translate — switch provider syntax

When to use: you authored a prompt for Claude using XML tags,
then added GPT-4o to the cohort, and the GPT result is mediocre
because the XML tags are noise to it.

A subtle non-blocking banner appears above the editor: "This
prompt uses Claude XML syntax. Translate it to GPT-4o style?"
Three actions: Translate / Keep as-is / Don't suggest
again.

Translate generates per-provider variants for multi-provider
cohorts so you can have one prompt → multiple syntactic forms,
without changing intent.

📸 Screenshot 19 — Translate banner above the editor
Capture: the Prompt Studio main view with the translate banner
visible above the editor (purple/blue accent), the three action
buttons clearly readable. The editor below should show the
XML-tagged prompt that triggered the suggestion.

6.5 Inline coach hints

When to use: an eval rule failed, or cost / latency exceeded
your stated constraints. The Lab Assistant proactively surfaces
suggestions tied to the specific failure.

A small 💡 Lab Assistant has 2 suggestions badge appears
inside the result card. Click to expand into a coach panel.
Each suggestion is a discrete card with a one-line title,
rationale, and three actions: Apply to prompt, Show me the
diff, Dismiss (with Dismiss permanently option for
noisy hints).

📸 Screenshot 20 — Coach panel expanded
Capture: a result card with the coach panel expanded
underneath, showing 2 suggestion cards. The triggering eval
failure badge ("Output too long — caps at 200 tokens") should be
visible at the top of the result card so the cause-and-effect
reads clearly.

6.6 Explain this run

When to use: a model returned something weird and you want a
plain-English explanation before you start guessing.

Click the Explain icon on a result card. Modal opens showing:

• What happened — concrete observation about the output.
• Why — model-aware reasoning for the behaviour.
• Suggested fix — a concrete prompt edit, one-click apply.

Example: "The model returned 3 bullets instead of 5 because
the prompt asks for 'a few' which Claude interpreted
conservatively. Suggested fix: replace 'a few' with 'exactly
5'."

📸 Screenshot 21 — Explain modal
Capture: the Explain modal open over the studio, with all three
sections visible (What happened / Why / Suggested fix). Show the
"Apply this fix" button at the bottom and the thumbs-up/down
rating in the corner.

---

A scenario is a saved comparison setup: prompt + cohort of
models + fixed inputs + eval rules. Once saved, every run against
the scenario is grouped into an execution group, every Lab
Assistant action is appended to a labAssistantHistory[]
timeline (FIFO-capped at 200 entries), and you can replay or
diff any past run with one click.

7.1 Save a scenario

After you've configured a useful comparison setup in Prompt
Studio, click Save As Scenario. Give it a name + optional
description.

📸 Screenshot 22 — Save scenario dialog
Capture: the Save Scenario dialog with name and description
filled in, the locked-in prompt preview visible at the bottom of
the dialog so users see "this is what gets snapshotted".

7.2 Scenario history banner

Once a scenario is active, every Lab Assistant operation
(Compose, Optimize, Refine, Translate, Explain) automatically
appends to the scenario's history with the request, result,
applied/discarded outcome, and the lab-assistant interaction id
for thumbs-up/down telemetry.

If you take a Lab Assistant action without an active scenario, a
yellow banner appears above the editor: "This optimization
isn't being tracked. Save it to a scenario to keep the full
optimization history." — click Create scenario and the
queued event lands.

📸 Screenshot 23 — SaveToScenarioBanner
Capture: the yellow "save iteration" banner above the editor,
operation label visible ("This optimization isn't being
tracked"), Create scenario / × dismiss buttons on the right.

7.3 Scenario timeline

Sidebar → Scenarios → click any → History tab. Reverse
chronological list of every Lab Assistant action with diff and
applied/discarded badge.

---

Eval rules attach to a prompt and check every run's output
against a condition. They turn "looks fine" into "passed 47
checks" and make regressions visible.

8.1 Rule types

• Contains — output must contain a specific substring.
• Regex — output must match a pattern.
• Length cap — token / character cap.
• Latency cap — wall-clock cap.
• Cost cap — per-run cost cap.
• JSON schema — output must validate against a JSON schema.
• LLM judge — Lab Assistant scores the output against a
  rubric you write in plain English. Powered by the
  judge operation under the hood.

8.2 Add a rule

In Prompt Studio, scroll to the Evaluators section below the
inputs panel.

1. Pick a rule type.
2. Fill in the value (substring, regex, schema, rubric).
3. Save.

Every subsequent run scores against the rule. Failures show as a
red badge on the relevant result card and trigger inline coach
hints.

📸 Screenshot 24 — Evaluators panel
Capture: the Evaluators panel below the prompt editor with 2-3
rules already configured, mix of types (one Contains, one Length
cap, one LLM judge with a visible rubric textarea). The "+ Add
evaluator" button should be visible.

---

Sidebar → Cost Analytics. Three panels:

9.1 Spend breakdown

Stacked bar of cost over time, sliceable by provider, model,
prompt, scenario.

9.2 Cache Hit Potential

This is the under-rated power feature. Even though PromptLab's
cache is in measurement mode (Phase 1 — see roadmap), the
Cache Hit Potential card shows how many of your last-30-day
runs were duplicate calls (same prompt + version + inputs +
model). The four tiles:

• Hit Rate — % of runs that are duplicates (color-coded:
  green ≥30%, amber 10-30%, red <10%).
• Duplicate Calls — absolute count.
• Unique Prompts — how many distinct prompts make up the
  duplicate volume.
• Estimated Savings — what you'd have saved if hits were
  served from cache.

📸 Screenshot 25 — Cache Hit Potential card
Capture: the Cache Hit Potential card from the Cost Analytics
dashboard with the four tiles populated and the decision-rule
copy visible underneath. Pick a project with at least amber-tier
hit rate so the data tells a story.

9.3 Per-provider / per-model pie

Pie chart of spend by provider / model. Useful for spotting "I'm
paying way more for Anthropic than I thought" before the bill
arrives.

---

This is where PromptLab becomes a load-bearing piece of your
production stack.

10.1 Get a project API key

Sidebar → Project Settings → API Keys → + Create.

Keys are plp_<keyId>_<secret> shape. Copy it once — it's not
shown again.

📸 Screenshot 26 — API Keys page after creating a key
Capture: the API Keys page right after creating a key, with the
"Copy this — you won't see it again" warning visible, the
masked key shown next to the Reveal button, and the Revoke
action.

10.2 Install the SDK

npm install @verna/promptlab-router-ts-sdk

10.3 Execute a prompt

import { PromptLabClient } from '@verna/promptlab-router-ts-sdk';

const client = new PromptLabClient({
  baseUrl: 'https://router.promptlab.vernalabs.net',
  projectId: '<your project id>',
  apiKey: process.env.PROMPTLAB_API_KEY!,
});

const result = await client.execute('article-summariser', {
  inputs: { articleText: rawArticle },
  // omit `version` to use the active version; pin a specific
  // version for canary deploys.
});

console.log(result.outputText);
console.log(result.cost.totalUsd);

result is the UnifiedExecutionResponse envelope — same
shape across text, image, video, audio. Your code handles one
response shape regardless of which provider the prompt's default
model belongs to.

10.4 Idempotent prompt push (CI / prompts-as-code)

Prompts can also be created or updated from CI:

curl -X PUT 
  "https://router.promptlab.vernalabs.net/v1/<projectId>/prompts/article-summariser" 
  -H "x-api-key: $PROMPTLAB_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Article Summariser",
    "description": "Bullet summary of news articles",
    "userPrompt": "Summarise:nn{{articleText}}",
    "inputs": [{"name":"articleText","type":"string","required":true}],
    "outputFormat": "text",
    "defaultModel": "openrouter::anthropic/claude-sonnet-4.5",
    "tags": ["summarisation"]
  }'

Every PUT creates a new active version. Old versions stay
queryable. Prompts-as-code with versioned changelogs.

10.5 Async execution (media generation)

For image / video / music generations the response includes a
jobId instead of an asset URL. Poll:

const submitted = await client.execute('hero-image-generator', {
  inputs: { subject: 'a robot', setting: 'a forest' },
});
// submitted.mode === 'async'
// submitted.jobId === '...'

let job = submitted;
while (job.status !== 'completed' && job.status !== 'failed') {
  await sleep(2000);
  job = await client.getJob(job.jobId);
}
console.log(job.outputs[0].url);

---

11.1 Provider tiers (today)

PromptLab speaks OpenAI, Anthropic, Google,
OpenRouter, FAL, Replicate, Mureka natively. Most
of the rest of the top-10 (xAI Grok, Meta Llama, DeepSeek,
Mistral, Cohere, Alibaba Qwen, Perplexity Sonar) are reachable
today via OpenRouter.

The defaultModel syntax is <provider>::<model-id>:

• anthropic::claude-sonnet-4.5
• openai::gpt-4o
• google::gemini-2.5-pro
• openrouter::anthropic/claude-sonnet-4.5
• openrouter::xai/grok-4
• openrouter::deepseek/deepseek-r2
• fal::fal-ai/flux-pro/v1.1

Use OpenRouter when you don't have direct keys yet — one
account, hundreds of models. Switch to direct provider keys when
you outgrow the openrouter convenience and need native discounts
(Anthropic prompt caching, OpenAI Batch API, etc.).

11.2 Provider Health column

The Providers page shows Provider Health per account — green
/ amber / red derived from the latest hourly latency canary. If
a provider is having a bad day, the badge tells you before your
users do.

📸 Screenshot 27 — Provider Health badges
Capture: the Providers page with at least one account in green,
one in amber (latency elevated), and (if possible) one in red
(failure rate >5%). If no real amber/red exists, capture only the
green ones — never fake the data.

---

Every run — manual or programmatic — lands in the
Interactions explorer with full request, response, cost,
timing, and raw provider payload captured.

Sidebar → Interactions. Filter by:

• Date range (default: last 24h, live updates).
• Prompt + version.
• Model.
• Status (succeeded / failed / cancelled).
• Cost range.

Click any row for the Interaction Detail page — the
canonical place to debug a single run.

12.1 Interaction Detail page

Three sections:

• Request — rendered template, inputs, model parameters,
  timing breakdown.
• Response — output text / asset, eval results, cost.
• Raw provider payload — the exact JSON sent to and received
  from the provider, useful when something looks weird at the
  protocol layer.

The Open in Prompt Studio button at the top loads the
prompt + inputs back into Studio for re-running. The Explain
this run button calls the Lab Assistant explain operation
directly on this interaction.

📸 Screenshot 28 — Interaction Detail page
Capture: the Interaction Detail page populated, showing the
three section headers, with the Open in Prompt Studio and
Explain this run buttons visible at the top. Pick an
interaction with a moderately interesting failure or near-miss
output so the page reads like real debugging, not a happy-path
showcase.

12.2 Replay

The Replay button re-executes the interaction with the same
inputs and current active prompt version. Useful for "did v4
actually fix the issue?" — replay v3's failing interactions
against v4 and check the eval-pass rate.

---

Workflow A — "I have a task, give me a working prompt today"

1. Create project, add OpenRouter key.
2. Pin Claude Sonnet 4.5 + GPT-4o + Gemini 2.5 in Models page.
3. Prompt Studio → ✨ Compose with AI → describe the task →
   pick the Claude variant → Apply.
4. Run All → look at the three model outputs side by side.
5. Pick the best one. Click ✨ Optimize → for the chosen model
   → Apply. Run All again.
6. Save Prompt → New prompt mode → ✨ Suggest name → ✨ Suggest
   tags → Save.
7. Get an API key → call client.execute('<promptId>', {...})
   from your code.

Workflow B — "I have a prompt that's slipping in quality"

1. Sidebar → Prompts → click the prompt → Open in Prompt
   Studio.
2. Add an eval rule that captures the slipping behaviour
   ("output must contain the article date").
3. Run All on a sample of 5 representative inputs.
4. When a run fails the eval, the inline 💡 Lab Assistant has
   N suggestions badge appears on the failing card. Expand →
   pick the most relevant suggestion → Apply.
5. Run All again. Confirm green badges.
6. Save Prompt → Save new version → Save.
7. (Later) Sidebar → Interactions → filter to the prompt → see
   eval pass rate trending up version-over-version.

Workflow C — "I'm migrating from GPT-4 to Claude"

1. Open the prompt in Prompt Studio.
2. Add Claude Sonnet 4.5 to the cohort. Translate banner
   appears.
3. Click Translate → review the diff → Apply.
4. Run All. Compare outputs side-by-side, run a few different
   inputs.
5. Click ✨ Optimize → Optimize for one model → Claude. Apply.
6. Save new version. Pin Claude as the new default model.
7. Set the previous GPT-4-based version's version param in
   your code as a 10% canary; flip to 100% Claude when the
   eval-pass rate matches or beats GPT-4.

Workflow D — "I'm running a fair comparison across 5 models"

1. Open a fresh Prompt Studio session.
2. Pick 5 models from across providers (Claude, GPT, Gemini,
   Llama-via-Groq, DeepSeek).
3. ✨ Compose with AI → fill the form → set the cohort = all 5
   models.
4. Apply one of the variants. The prompt is currently
   provider-leaning.
5. ✨ Optimize → Optimize for cohort → Apply. Now the prompt
   is provider-agnostic.
6. Run All. Read the perModelNotes panel for warnings about
   each model's likely interpretation.
7. Save As Scenario → name it. Subsequent runs land in the
   scenario's execution-group history for trend analysis.

---

Operation	Where	What it does
metaprompt	✨ Compose with AI	Full prompt from natural-language task description, per target model
coach	💡 Inline coach hints	Targeted edits when an eval rule fails or constraints are exceeded
optimize	Optimize sheet, Mode = single	Full rewrite for one target model with projected eval delta
optimize-for-cohort	Optimize sheet, Mode = cohort	Provider-agnostic rewrite for an entire cohort + per-model interpretation notes
refine	Optimize sheet, Mode = refine	Smallest possible edit that addresses a free-form note
translate-syntax	Translate banner	Cross-provider syntax translation (Claude XML ↔ GPT structured ↔ Gemini markdown)
explain	💬 Explain this run	Plain-English what-happened / why / suggested fix for one interaction
auto-name	Save dialog → ✨ Suggest name	Short title from prompt or scenario content
auto-tag	Save dialog → ✨ Suggest tags	Tag list reusing existing project taxonomy
judge	Eval rules → LLM judge type	Score output against a free-text rubric

All ten run through the dedicated lab-assistant PromptLab
project (PromptLab dogfooding itself). The default model for
every assistant prompt is
openrouter::anthropic/claude-sonnet-4.5 — cost is absorbed by
PromptLab as platform overhead.

---