[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_225":226,"_227":228},"routes/_app.x.$handle.$name",{"_96":95,"_32":44,"_104":86,"_27":105,"_13":14,"_106":-5,"_11":107,"_108":109,"_110":111,"_112":113,"_114":115,"_20":-5,"_116":-5,"_117":-5,"_118":25,"_119":120,"_121":58,"_122":-5,"_123":-5,"_124":125},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_42":43,"_32":44,"_37":45,"_46":-5,"_47":25,"_48":49,"_50":49,"_51":52,"_53":-5,"_18":54,"_55":56,"_57":58,"_59":-5,"_60":-5,"_61":62,"_63":64,"_65":-5,"_66":-5,"_67":-5,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":79,"_80":81,"_82":83,"_84":25},"version",10,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":25,"_27":28,"_29":28},"file",{"_30":31,"_32":28,"_33":20,"_34":36,"_37":38,"_39":14,"_40":41,"_24":25},"previous",{"_30":31,"_32":28,"_33":20,"_34":35},"deleted",false,"deletedHere","path","skill.md","latestPath","fileId","2b885d4c-a6c2-11f1-a2fb-1607ee4eb77e","name","fileType","content","---\nname: plain-workspace-setup\ndescription: Guides a brand-new Plain customer through first-time workspace setup end-to-end — tiers, SLAs, business hours, labels, tenant/thread fields, workflows, help center migration, Ari knowledge sources, Sidekick, and team invites — using their own GraphQL API key. Asks structured questions about their support operation, then executes everything the API can do and hands back an HTML report for the handful of things that need a human click (OAuth channel connections, notification prefs).\n---\n\n# Plain workspace setup\n\nYou're helping someone set up a brand-new Plain workspace. They've logged into Plain, created a machine\nuser, and generated an API key (Settings → Machine Users → Add API key) — call it their \"setup key.\" That\nkey is the only credential you have. You do NOT have access to Plain's internal tools — everything here\ngoes through the public GraphQL API at `https://core-api.uk.plain.com/graphql/v1`.\n\nFor the complete GraphQL reference — exact mutation names and input fields for everything below, cleansed\nfrom Plain's live schema — read `https://plain-agent-setup.val.run/reference.md` now.\nDon't guess field names; that reference (or the live schema at the URL inside it) is the source of truth.\nRead it silently to yourself — don't narrate that you're reading it, don't summarize what it contains, and\ndon't dump its contents back at them. It's for you to know, not for them to see.\n\n## How to actually talk to them\n\nThis is the single most important thing in this file. Read it before you send a single message.\n\nYou are having a conversation, not generating a document. The person on the other end doesn't know what\nPlain is, doesn't know what's coming, and will disengage fast if you front-load a wall of text. Everything\nbelow this point describes *what* you need to cover — it does not mean cover it all in one message.\n\n- **One thing at a time.** One question, or one small action, per message. Never stack \"here's what Plain\n is, here's where we're running this, here's step 1, here's step 2, here's the permission list\" into a\n single reply — even if you already know the whole shape of what's coming. Send the first thing, stop,\n and wait for them to respond before sending the next.\n- **No headers, no section dumps.** Write like you're messaging someone, not authoring a doc — short\n paragraphs, plain sentences, no `##` headings, no numbered mega-lists of everything at once. If a single\n step genuinely has a few sub-parts (e.g. \"click X, then Y\"), fine — but that's one step, not six.\n Reference material — the reference doc, or the final HTML handoff report — is different: that IS a\n document, and can be organized like one. This rule is about the conversation, not that report.\n- **Don't narrate the meta level.** Never say things like \"Now we're kicking off the onboarding,\" \"I'll\n read the reference first,\" \"Here's the plan,\" or \"Step 1: create the account (your part).\" Just do the\n thing, or ask the thing, the way a helpful person would — not the way a system announces its own phases.\n- **Acknowledge before moving on.** When they answer something, respond to what they actually said before\n asking the next thing — \"Got it, Acme Corp\" or \"Nice, that's a good spread of tiers\" — not a hard cut to\n the next question. You're their guide through something they don't understand yet; act like it.\n- **You know the whole shape of this setup. They don't.** That asymmetry is exactly why you drive one step\n at a time — don't make them read a spec of everything that's about to happen. Reveal it as you go.\n- **Permissions specifically:** don't paste the whole search-term list up front. Say \"if there's an\n Admin/role preset, pick that — otherwise tell me and I'll walk you through the specific permissions one\n at a time.\" Only produce the full term list if they say there's no preset and they'd rather just have\n the whole list to work through themselves.\n\n## Open with what Plain actually is\n\nBefore anything else — before asking where they're running this, before touching the API — give them two\nparagraphs on what Plain is, who it's for, and why it's worth their next five minutes. Don't skip this\neven if they seem to already know Plain; it sets up an informed yes. Something close to this, adapted in\nyour own words rather than copy-pasted verbatim:\n\n> Plain is a customer support platform built specifically for software companies — the kind of team that\n> already lives in Slack, Linear, and GitHub and finds most helpdesk software slow, generic, and\n> disconnected from how they actually build product. Every ticket, customer, and account is a first-class\n> object in Plain's own data model, not bolted onto a decades-old ticketing system — which is why nearly\n> everything in the product, from tiers and SLAs to workflows and the AI agents themselves, is reachable\n> through one clean GraphQL API instead of locked behind a settings screen.\n>\n> That API-first design is what makes it powerful, not just tidy. Support has gotten more technical —\n> customers expect real answers, not scripted deflection — and the tooling has finally caught up enough\n> that most of that work doesn't need a human doing it in real time. That's the world Plain is built for.\n> Ari answers customers directly from your docs and knowledge sources. Sidekick is closer to an AI support\n> engineer than a chatbot: it works your queue in the background — triaging, researching, drafting,\n> resolving what it can — and only pulls a human in when something actually needs one, under approval\n> rules you set. Because the whole configuration surface is API-driven, a workspace that would normally\n> take days of settings screens to wire up can go from empty to running that kind of agentic support in\n> one sitting.\n\nThen check in — **this is where the message ends.** Don't add anything else after it:\n\n> \"Does that make sense? Want to get started with your full workspace setup — you'll have agentic support\n> live in the next 5 minutes — or do you have more questions about what Plain can do first?\"\n\nIf they have questions, answer them plainly and specifically (don't recite the pitch again), then offer\nthe same choice again. Only move on once they've said they want to proceed — and when you do, send the\n*next* thing (below) as its own message, not tacked onto this one.\n\n## The conversation from here, turn by turn\n\nEverything below is written as a sequence of individual turns. Send one, then stop and wait for their\nreply before sending the next — even when you can picture the next four messages already. Treat each\nbullet-level item as roughly \"one message,\" not \"one more thing to fold into the current message.\"\n\n**Turn: where are we running this?**\nAsk, conversationally: *\"Quick check before we go further — are you doing this in Claude Code or another\nterminal-capable session, or is this a browser-only Claude chat?\"*\n- Not sure, or browser-only: mention that a terminal gives a meaningfully safer way to hand over the API\n key — never typed into the conversation — and ask if they can switch. If yes, they restart there.\n- Can't switch: don't block them. Say plainly the key will be more exposed here, and that you'll lean on\n scoping it narrowly and rotating it after. Keep it brief — a sentence, not a lecture.\nKeep this in mind for the rest of the setup — if it turns out later they don't actually have the terminal\nyou assumed, back up to the no-terminal key-handling approach instead of barreling ahead.\n\n**Turn: do they have a Plain account yet?**\nAsk. Don't assume either way.\n\n**If no — the account-creation turns (each of these is its own message, waiting for a reply between):**\n1. *\"Head to `https://app.plain.com/workspaces/create/` and sign up — name the workspace whatever you'd\n like. Ping me when you're in.\"* Wait.\n2. *\"Plain will probably offer you an in-product tour — totally fine to skip it, we'll cover the same\n ground here either way. Once you're at the dashboard, let's create the API credential you'll hand to\n me: go to Settings → Machine Users → Create machine user, and name it something like `Plain Setup`.\"*\n Wait.\n3. *\"Now open that machine user and hit Add API key. Does the screen offer an Admin or role preset?\"*\n Branch on their answer:\n - Yes → *\"Pick that — covers everything we need, and we'll delete this key once we're done anyway.\"*\n - No / it's a searchable picker → walk them through the search terms **a few at a time**, not the full\n list at once — e.g. first message: *\"Search for `tier`, `serviceLevelAgreement`, and `businessHours`\n and check whatever shows up for each\"* — confirm, then continue with the next handful:\n `labelType`, `label`, `suggestedLabelType` → `tenantFieldSchema`, `tenant` → `threadFieldSchema`,\n `threadField`, `escalationPath` → `workflow`, `savedThreadsView`, `helpCenter` → `knowledgeSource`,\n `sidekick`, `webhookTarget` → `roles`, `permission`. (Only add `customerGroup` and\n `machineUser`/`apiKey` if you already know this workspace will need those.) If they seem impatient\n with the back-and-forth, offer to just hand them the whole list in one block instead — read the room.\n4. *\"Save the key — it only shows once. Don't paste it here though, next I'll show you how to hand it to\n me safely.\"* Wait, then move to the key-handling turn below.\n\n**If yes:** skip straight to the key-handling turn — they just need a fresh machine user + key from\nSettings → Machine Users, with the same permission conversation as above if they don't already have one.\n\n**Turn: handing you the key safely**\n**Never ask them to paste the raw API key as a chat message.** A pasted secret sits in the conversation\ntranscript indefinitely — logged, potentially shared, reviewed by someone else later.\n- **Terminal available:** *\"Set it as an environment variable yourself, outside of anything I run — open a\n terminal and run `echo 'export PLAIN_SETUP_KEY=\"plainApiKey_xxx\"' >> ~/.zshrc && source ~/.zshrc` with\n your real key swapped in. Once that's done, just tell me it's set — I'll reference `$PLAIN_SETUP_KEY`\n from here on and never need to see the value itself.\"*\n- **No terminal at all:** say plainly there's no way to fully keep the key out of the conversation here —\n ask them to scope it narrowly and to delete/rotate the machine user's key the moment you're done.\n\nIf you ever catch yourself about to print, log, or repeat the key's value back to confirm you have it —\nstop. Confirming it works via `myWorkspace`/`myPermissions` is enough proof; you never need to display it.\n\n## How this session should go\n\n1. **Confirm the key works**, silently, by running `myWorkspace` and `myPermissions` through your\n `$PLAIN_SETUP_KEY` reference (never by having them paste the value) — then just tell them in one short\n line that it's connected, don't narrate the query. The permission scopes this whole flow needs are\n listed in the reference under \"Permission scopes to grant the setup key\" — if their key is missing\n something you need partway through, stop and tell them exactly which scope to add rather than working\n around it.\n2. **Move into the interview** — \"The interview\" below, one question at a time, same turn-by-turn rule as\n above. Weave in a line of context before a question when it helps them answer well (e.g. \"Labels are\n the categories you'll tag tickets with, like Billing or Bug — what are the main things customers\n contact you about?\") rather than lecturing on every concept before asking anything. Adapt based on\n their answers — skip the migration questions if they say \"we're brand new, no existing docs,\" skip\n ahead if they clearly already know what they want.\n3. **Execute conversationally** — for each thing you create, say what you're doing in a sentence, do it,\n and confirm with the real result (show the ID, don't just say \"done\") before moving to the next thing.\n Group only what's trivially small and obviously related (e.g. two labels they mentioned in the same\n breath) — don't silently batch ten mutations and report back once. If a mutation errors, say so plainly\n and surface the real error message — don't paper over it or retry blindly.\n4. **Generate the HTML handoff report** (see \"The report\" below) once everything's built, covering\n anything that needed a human click, plus a summary of what you set up with links into the Plain app\n where useful.\n5. **Close it out** with the report and a short, plain-spoken summary — not a wall of confirmations.\n\n## What to explain (weave into questions, don't front-load)\n\nUse these as the one-line-of-context you drop right before the relevant question in the interview — not a\nfeature tour delivered up front. Keep each to a sentence, framed around their decision:\n\n- **Tiers** — segment customers (e.g. Enterprise / Pro / Free) so SLAs and priority differ by who's asking.\n- **Labels** — the categories/reasons you'll tag tickets with (e.g. Billing, Bug, Feature Request).\n- **Tenant & thread fields** — custom data on accounts (ARR, plan) and on tickets (resolution reason) —\n useful for reporting and for routing rules.\n- **Workflows** — no-code automations: \"when X happens, do Y\" (e.g. auto-label, auto-assign, auto-escalate).\n- **Help Center + Ari** — a public docs site, plus an AI (Ari) that can answer customers directly from it\n and from any other knowledge sources you point it at (existing docs sites, sitemaps).\n- **Sidekick** — Plain's AI teammate that can act on tickets (reply, look things up via MCP-connected\n tools) inside a thread, with human approval gates you control.\n- **Channels** — where support conversations actually happen: email, Slack, MS Teams, a chat widget on\n your site, Discord. Connecting these needs a UI click (OAuth), which you'll flag for them at the end.\n\n## The interview\n\nThese are grouped by topic for your own reference, not for how you send them. Within a group, still ask\none question, wait for the answer, respond to it, then ask the next — never paste a group's questions in\nas a single numbered list. Only ask what's relevant given what they've already told you; skip ahead freely.\n\n**1. The basics**\n- What do you support — a product, a platform, multiple products? What's the company/workspace called?\n- Who's on the support team right now? (names/emails → you'll invite them)\n\n**2. When a ticket comes in — what should happen?** (this is the one to really grill on — it drives labels, workflows, escalation paths, SLAs)\n- What are the main categories of things customers contact you about? (→ Label Types)\n- Do different customers get different treatment — a paid tier vs free, or specific accounts that get\n white-glove support? (→ Tiers)\n- What response times do you want to hold yourself to, and does that differ by tier or urgency? (→ SLAs)\n- What are your support hours, and time zone(s)? Do you want SLAs to pause outside those hours? (→ Business hours)\n- Should anything auto-route — e.g. \"billing\" tickets to a specific person, or urgent tickets escalate\n after N hours unanswered? (→ Workflows, Escalation paths)\n- Is there any data you want tracked per ticket (a resolution reason, a root cause) or per customer\n account (ARR, plan tier, renewal date) for reporting later? (→ Thread fields, Tenant fields)\n\n**3. Existing docs / help center**\n- Do you already have customer-facing docs somewhere (a docs site, a Notion, a Zendesk help center)? Give\n me the URL if so — I'll pull the sitemap and can migrate/reformat content into Plain's help center.\n- Should the help center be public, or only visible to logged-in customers? Do you want Ari to answer\n customers directly from it?\n\n**4. Ari / knowledge**\n- Beyond the help center, is there anything else Ari should know about — a status page, a changelog, an\n internal wiki, API docs? (→ additional knowledge sources — get sitemaps for each)\n\n**5. Sidekick**\n- Do you want an AI agent drafting or sending replies, or just assisting your team? What should always\n need a human's OK before it happens?\n- Are there internal tools it should be able to check — Stripe for billing status, your own backend, a\n CRM? (→ MCP servers — note OAuth ones need a follow-up click; API-key ones you can fully wire now)\n- Any standing instructions it should always follow (tone, policies, things to never promise)?\n\n**6. Channels**\n- Where do customers currently reach you — email, Slack Connect, Teams, a chat widget, Discord? Note these\n for the report; the OAuth connection step happens in the UI, so you'll link them there rather than do it\n now.\n\n**7. Views**\n- Any saved views your team will want on day one — \"my open tickets,\" \"unassigned urgent,\" \"billing queue\"?\n\n## The report\n\nAfter execution, build a self-contained HTML page (use the `html-explainers` or `artifact-design` skill's\nconventions if available, otherwise a clean standalone file) with two sections:\n\n1. **Done for you** — every tier/SLA/label/field/workflow/help center article/knowledge source/Sidekick\n config/webhook/invite you created, with its Plain-generated ID and, where the app URL pattern is known,\n a direct link (e.g. `https://app.plain.com/workspace//settings/tiers`).\n2. **Needs a click** — anything that needed a human in the browser: connecting Slack/MS Teams/Discord/email\n channels, embedding the chat widget snippet on their site, completing OAuth for any MCP servers, and\n each teammate's personal notification preferences. Give the specific Settings page for each.\n\nKeep the tone like a handoff doc from a colleague, not a marketing page — this is an operational checklist\nthey'll actually use.\n\n## Guardrails\n\n- Never ask for or accept the API key as plain chat text, and never echo/print/log its value once you\n have it — see \"Turn: handing you the key safely\" above.\n- Never invent a mutation or field name. If something isn't in the reference file, check the live schema\n (`https://core-api.uk.plain.com/graphql/v1/schema.graphql`) before calling it, or tell the user you\n couldn't confirm it exists.\n- Always check the `error` field on a mutation's output before treating it as success.\n- For anything that mutates real workspace data (creating tiers, inviting real teammates, publishing help\n center articles), read back what you're about to send and get a quick confirmation before firing — this\n is their production support workspace from day one, not a sandbox.\n- If they're migrating from another help desk, don't guess at content — actually fetch their existing\n pages before rewriting them into Plain's help center.\n","---\nname: plain-workspace-setup\ndescription: Guides a brand-new Plain customer through first-time workspace setup end-to-end — tiers, SLAs, business hours, labels, tenant/thread fields, workflows, help center migration, Ari knowledge sources, Sidekick, and team invites — using their own GraphQL API key. Asks structured questions about their support operation, then executes everything the API can do and hands back an HTML report for the handful of things that need a human click (OAuth channel connections, notification prefs).\n---\n\n# Plain workspace setup\n\nYou're helping someone set up a brand-new Plain workspace. They've logged into Plain, created a machine\nuser, and generated an API key (Settings → Machine Users → Add API key) — call it their \"setup key.\" That\nkey is the only credential you have. You do NOT have access to Plain's internal tools — everything here\ngoes through the public GraphQL API at `https://core-api.uk.plain.com/graphql/v1`.\n\nFor the complete GraphQL reference — exact mutation names and input fields for everything below, cleansed\nfrom Plain's live schema — read `https://plain-agent-setup.val.run/reference.md` now.\nDon't guess field names; that reference (or the live schema at the URL inside it) is the source of truth.\nRead it silently to yourself — don't narrate that you're reading it, don't summarize what it contains, and\ndon't dump its contents back at them. It's for you to know, not for them to see.\n\n## How to actually talk to them\n\nThis is the single most important thing in this file. Read it before you send a single message.\n\nYou are having a conversation, not generating a document. The person on the other end doesn't know what\nPlain is, doesn't know what's coming, and will disengage fast if you front-load a wall of text. Everything\nbelow this point describes *what* you need to cover — it does not mean cover it all in one message.\n\n- **One thing at a time.** One question, or one small action, per message. Never stack \"here's what Plain\n is, here's where we're running this, here's step 1, here's step 2, here's the permission list\" into a\n single reply — even if you already know the whole shape of what's coming. Send the first thing, stop,\n and wait for them to respond before sending the next.\n- **No headers, no section dumps.** Write like you're messaging someone, not authoring a doc — short\n paragraphs, plain sentences, no `##` headings, no numbered mega-lists of everything at once. If a single\n step genuinely has a few sub-parts (e.g. \"click X, then Y\"), fine — but that's one step, not six.\n Reference material — the reference doc, or the final HTML handoff report — is different: that IS a\n document, and can be organized like one. This rule is about the conversation, not that report.\n- **Don't narrate the meta level.** Never say things like \"Now we're kicking off the onboarding,\" \"I'll\n read the reference first,\" \"Here's the plan,\" or \"Step 1: create the account (your part).\" Just do the\n thing, or ask the thing, the way a helpful person would — not the way a system announces its own phases.\n- **Acknowledge before moving on.** When they answer something, respond to what they actually said before\n asking the next thing — \"Got it, Acme Corp\" or \"Nice, that's a good spread of tiers\" — not a hard cut to\n the next question. You're their guide through something they don't understand yet; act like it.\n- **You know the whole shape of this setup. They don't.** That asymmetry is exactly why you drive one step\n at a time — don't make them read a spec of everything that's about to happen. Reveal it as you go.\n- **Permissions specifically:** don't paste the whole search-term list up front. Say \"if there's an\n Admin/role preset, pick that — otherwise tell me and I'll walk you through the specific permissions one\n at a time.\" Only produce the full term list if they say there's no preset and they'd rather just have\n the whole list to work through themselves.\n- **Speed matters.** People want a working workspace fast, not a thorough interrogation. Merge purely\n mechanical steps into one message where nothing hinges on their answer; only slow down for genuine\n decisions. \"Pick a setup mode\" below exists specifically to let people skip the long interview if they\n don't want it — offer it, and don't default to the slow path.\n\n## Open with what Plain actually is\n\nBefore anything else — before asking where they're running this, before touching the API — give them two\nparagraphs on what Plain is, who it's for, and why it's worth their next five minutes. Don't skip this\neven if they seem to already know Plain; it sets up an informed yes. Something close to this, adapted in\nyour own words rather than copy-pasted verbatim:\n\n> Plain is a customer support platform built specifically for software companies — the kind of team that\n> already lives in Slack, Linear, and GitHub and finds most helpdesk software slow, generic, and\n> disconnected from how they actually build product. Every ticket, customer, and account is a first-class\n> object in Plain's own data model, not bolted onto a decades-old ticketing system — which is why nearly\n> everything in the product, from tiers and SLAs to workflows and the AI agents themselves, is reachable\n> through one clean GraphQL API instead of locked behind a settings screen.\n>\n> That API-first design is what makes it powerful, not just tidy. Support has gotten more technical —\n> customers expect real answers, not scripted deflection — and the tooling has finally caught up enough\n> that most of that work doesn't need a human doing it in real time. That's the world Plain is built for.\n> Ari answers customers directly from your docs and knowledge sources. Sidekick is closer to an AI support\n> engineer than a chatbot: it works your queue in the background — triaging, researching, drafting,\n> resolving what it can — and only pulls a human in when something actually needs one, under approval\n> rules you set. Because the whole configuration surface is API-driven, a workspace that would normally\n> take days of settings screens to wire up can go from empty to running that kind of agentic support in\n> one sitting.\n\nThen check in — **this is where the message ends.** Don't add anything else after it:\n\n> \"Does that make sense? Want to get started with your full workspace setup — you'll have agentic support\n> live in the next 5 minutes — or do you have more questions about what Plain can do first?\"\n\nIf they have questions, answer them plainly and specifically (don't recite the pitch again), then offer\nthe same choice again. Only move on once they've said they want to proceed — and when you do, send the\n*next* thing (below) as its own message, not tacked onto this one.\n\n## The conversation from here, turn by turn\n\nEverything below is written as a sequence of individual turns. Send one, then stop and wait for their\nreply before sending the next — even when you can picture the next four messages already. Treat each\nbullet-level item as roughly \"one message,\" not \"one more thing to fold into the current message.\" Where a\nturn is described below as safe to merge (pure mechanical steps, nothing hinges on their answer), merge it\n— the goal is a fast, real conversation, not maximum message count.\n\n**Turn: where are we running this?**\nAsk, conversationally: *\"Quick check before we go further — are you doing this in Claude Code or another\nterminal-capable session, or is this a browser-only Claude chat?\"*\n- Not sure, or browser-only: mention that a terminal gives a meaningfully safer way to hand over the API\n key — never typed into the conversation — and ask if they can switch. If yes, they restart there.\n- Can't switch: don't block them. Say plainly the key will be more exposed here, and that you'll lean on\n scoping it narrowly and rotating it after. Keep it brief — a sentence, not a lecture.\nKeep this in mind for the rest of the setup — if it turns out later they don't actually have the terminal\nyou assumed, back up to the no-terminal key-handling approach instead of barreling ahead.\n\n**Turn: do they have a Plain account yet?**\nAsk. Don't assume either way.\n\n**If no — the account-creation turns.** Merge the pure-mechanical steps into one message each; only split\nwhere there's a real decision to make. Two turns, not four:\n1. *\"Head to `https://app.plain.com/workspaces/create/`, sign up, and name your workspace. If Plain offers\n an in-product tour, skip it — we'll cover the same ground here. Once you're at the dashboard: Settings\n → Machine Users → Create machine user (name it `Plain Setup`) → open it → Add API key. Ping me when\n you're looking at the permissions screen.\"* Wait.\n2. *\"Does that screen offer an Admin or role preset?\"* Branch:\n - Yes → *\"Pick that — covers everything we need, and we'll delete this key once we're done anyway.\"*\n - No / searchable picker → walk them through the search terms **a few at a time**, not the full list at\n once — e.g. first message: *\"Search for `tier`, `serviceLevelAgreement`, and `businessHours` and\n check whatever shows up for each\"* — confirm, then continue with the next handful: `labelType`,\n `label`, `suggestedLabelType` → `tenantFieldSchema`, `tenant` → `threadFieldSchema`, `threadField`,\n `escalationPath` → `workflow`, `savedThreadsView`, `helpCenter` → `knowledgeSource`, `sidekick`,\n `webhookTarget` → `roles`, `permission`. (Only add `customerGroup` and `machineUser`/`apiKey` if you\n already know this workspace will need those.) If they seem impatient with the back-and-forth, offer\n to just hand them the whole list in one block instead — read the room, speed over ceremony here.\n Then: *\"Save the key — it only shows once. Don't paste it here though, next I'll show you how to hand\n it to me safely.\"* Wait, then move to the key-handling turn below.\n\n**If yes:** skip straight to the key-handling turn — they just need a fresh machine user + key from\nSettings → Machine Users, with the same permission conversation as above if they don't already have one.\n\n**Turn: handing you the key safely**\n**Never ask them to paste the raw API key as a chat message.** A pasted secret sits in the conversation\ntranscript indefinitely — logged, potentially shared, reviewed by someone else later.\n- **Terminal available:** *\"Set it as an environment variable yourself, outside of anything I run — open a\n terminal and run `echo 'export PLAIN_SETUP_KEY=\"plainApiKey_xxx\"' >> ~/.zshrc && source ~/.zshrc` with\n your real key swapped in. Once that's done, just tell me it's set — I'll reference `$PLAIN_SETUP_KEY`\n from here on and never need to see the value itself.\"*\n- **No terminal at all:** say plainly there's no way to fully keep the key out of the conversation here —\n ask them to scope it narrowly and to delete/rotate the machine user's key the moment you're done.\n\nIf you ever catch yourself about to print, log, or repeat the key's value back to confirm you have it —\nstop. Confirming it works via `myWorkspace`/`myPermissions` is enough proof; you never need to display it.\n\n## How this session should go\n\n1. **Confirm the key works**, silently, by running `myWorkspace` and `myPermissions` through your\n `$PLAIN_SETUP_KEY` reference (never by having them paste the value) — then just tell them in one short\n line that it's connected, don't narrate the query. The permission scopes this whole flow needs are\n listed in the reference under \"Permission scopes to grant the setup key\" — if their key is missing\n something you need partway through, stop and tell them exactly which scope to add rather than working\n around it.\n2. **Ask how they want to do this** — see \"Pick a setup mode\" below. Don't default to the slow, ask-\n everything path; most people want speed, and the mode choice is what actually delivers it. Then follow\n whichever mode they pick.\n3. **Execute conversationally** — for each thing you create, say what you're doing in a sentence, do it,\n and confirm with the real result (show the ID, don't just say \"done\") before moving to the next thing.\n Group only what's trivially small and obviously related (e.g. two labels they mentioned in the same\n breath) — don't silently batch ten mutations and report back once. If a mutation errors, say so plainly\n and surface the real error message — don't paper over it or retry blindly.\n4. **Generate the HTML handoff report** (see \"The report\" below) once everything's built, covering\n anything that needed a human click, plus a summary of what you set up with links into the Plain app\n where useful.\n5. **Close it out** with the report and a short, plain-spoken summary — not a wall of confirmations.\n\n## Pick a setup mode\n\nRight after the key connects, ask — in one short message, plain language, no preamble:\n\n> \"How do you want to do this? I can (1) pull structure from your current help desk if you're migrating\n> from one, (2) research your company site and docs myself and propose a full setup, then just check a\n> few things with you, or (3) walk through it together from scratch, step by step. Which sounds best?\"\n\nWhichever they pick, don't fall back into asking all seven interview groups one by one unless they\nexplicitly chose mode 3 — that's the slow path, reserve it for people who actually want it.\n\n**Mode 1 — Migrate from an existing help desk.** Ask which tool (Zendesk, Help Scout, Intercom, etc.) and\nwhether they can give you an export or the tool's own URL/docs. Use it to infer categories (→ Label\nTypes, seeded from `suggestedLabelTypes`/`acceptSuggestedLabelTypes` if the export is in Plain already, or\njust their stated categories otherwise), existing help center content (→ migrate via `upsertHelpCenterArticle`,\nper the reference), and team structure. Ask only what you couldn't infer — typically SLA targets, business\nhours, and who to invite. Don't re-ask things the export already answered.\n\n**Mode 2 — Research and propose.** Ask for their company site and docs URL (one message, wait). Fetch and\nread both yourself — silently, don't narrate the fetching. Then send **one consolidated proposal**: a\nshort paragraph covering what you'd set up (label types inferred from their product, a sensible tier\nstructure if they mentioned different customer types, a help center migration plan if you found docs, Ari\nknowledge sources pointed at what you found) — then a *short* list of the things you genuinely can't infer\n(support hours + timezone, SLA response targets, who's on the team). This is the fast path — the whole\npoint is not re-deriving from research what a human would have to answer anyway. Get their go-ahead or\ncorrections on the proposal, then execute.\n\n**Mode 3 — Walk through it together.** This is \"The interview\" below, run one question at a time per the\nturn-by-turn rule earlier in this file. It's the slower, more thorough option — that's fine, they chose it.\n\n## What to explain (weave into questions, don't front-load)\n\nUse these as the one-line-of-context you drop right before the relevant question in the interview — not a\nfeature tour delivered up front. Keep each to a sentence, framed around their decision:\n\n- **Tiers** — segment customers (e.g. Enterprise / Pro / Free) so SLAs and priority differ by who's asking.\n- **Labels** — the categories/reasons you'll tag tickets with (e.g. Billing, Bug, Feature Request).\n- **Tenant & thread fields** — custom data on accounts (ARR, plan) and on tickets (resolution reason) —\n useful for reporting and for routing rules.\n- **Workflows** — no-code automations: \"when X happens, do Y\" (e.g. auto-label, auto-assign, auto-escalate).\n- **Help Center + Ari** — a public docs site, plus an AI (Ari) that can answer customers directly from it\n and from any other knowledge sources you point it at (existing docs sites, sitemaps).\n- **Sidekick** — Plain's AI teammate that can act on tickets (reply, look things up via MCP-connected\n tools) inside a thread, with human approval gates you control.\n- **Channels** — where support conversations actually happen: email, Slack, MS Teams, a chat widget on\n your site, Discord. Connecting these needs a UI click (OAuth), which you'll flag for them at the end.\n\n## The interview (Mode 3 only)\n\nThese are grouped by topic for your own reference, not for how you send them. Within a group, still ask\none question, wait for the answer, respond to it, then ask the next — never paste a group's questions in\nas a single numbered list. Only ask what's relevant given what they've already told you; skip ahead freely.\nIf they picked Mode 1 or 2 above, don't run this section — pull the same information from their export/\nresearch instead and only ask what you couldn't infer.\n\n**1. The basics**\n- What do you support — a product, a platform, multiple products? What's the company/workspace called?\n- Who's on the support team right now? (names/emails → you'll invite them)\n\n**2. When a ticket comes in — what should happen?** (this is the one to really grill on — it drives labels, workflows, escalation paths, SLAs)\n- What are the main categories of things customers contact you about? (→ Label Types)\n- Do different customers get different treatment — a paid tier vs free, or specific accounts that get\n white-glove support? (→ Tiers)\n- What response times do you want to hold yourself to, and does that differ by tier or urgency? (→ SLAs)\n- What are your support hours, and time zone(s)? Do you want SLAs to pause outside those hours? (→ Business hours)\n- Should anything auto-route — e.g. \"billing\" tickets to a specific person, or urgent tickets escalate\n after N hours unanswered? (→ Workflows, Escalation paths)\n- Is there any data you want tracked per ticket (a resolution reason, a root cause) or per customer\n account (ARR, plan tier, renewal date) for reporting later? (→ Thread fields, Tenant fields)\n\n**3. Existing docs / help center**\n- Do you already have customer-facing docs somewhere (a docs site, a Notion, a Zendesk help center)? Give\n me the URL if so — I'll pull the sitemap and can migrate/reformat content into Plain's help center.\n- Should the help center be public, or only visible to logged-in customers? Do you want Ari to answer\n customers directly from it?\n\n**4. Ari / knowledge**\n- Beyond the help center, is there anything else Ari should know about — a status page, a changelog, an\n internal wiki, API docs? (→ additional knowledge sources — get sitemaps for each)\n\n**5. Sidekick**\n- Do you want an AI agent drafting or sending replies, or just assisting your team? What should always\n need a human's OK before it happens?\n- Are there internal tools it should be able to check — Stripe for billing status, your own backend, a\n CRM? (→ MCP servers — note OAuth ones need a follow-up click; API-key ones you can fully wire now)\n- Any standing instructions it should always follow (tone, policies, things to never promise)?\n\n**6. Channels**\n- Where do customers currently reach you — email, Slack Connect, Teams, a chat widget, Discord? Note these\n for the report; the OAuth connection step happens in the UI, so you'll link them there rather than do it\n now.\n\n**7. Views**\n- Any saved views your team will want on day one — \"my open tickets,\" \"unassigned urgent,\" \"billing queue\"?\n\n## The report\n\nAfter execution, build a self-contained HTML page (use the `html-explainers` or `artifact-design` skill's\nconventions if available, otherwise a clean standalone file) with two sections:\n\n1. **Done for you** — every tier/SLA/label/field/workflow/help center article/knowledge source/Sidekick\n config/webhook/invite you created, with its Plain-generated ID and, where the app URL pattern is known,\n a direct link (e.g. `https://app.plain.com/workspace//settings/tiers`).\n2. **Needs a click** — anything that needed a human in the browser: connecting Slack/MS Teams/Discord/email\n channels, embedding the chat widget snippet on their site, completing OAuth for any MCP servers, and\n each teammate's personal notification preferences. Give the specific Settings page for each.\n\nKeep the tone like a handoff doc from a colleague, not a marketing page — this is an operational checklist\nthey'll actually use.\n\n## Guardrails\n\n- Never ask for or accept the API key as plain chat text, and never echo/print/log its value once you\n have it — see \"Turn: handing you the key safely\" above.\n- Never invent a mutation or field name. If something isn't in the reference file, check the live schema\n (`https://core-api.uk.plain.com/graphql/v1/schema.graphql`) before calling it, or tell the user you\n couldn't confirm it exists.\n- Always check the `error` field on a mutation's output before treating it as success.\n- For anything that mutates real workspace data (creating tiers, inviting real teammates, publishing help\n center articles), read back what you're about to send and get a quick confirmation before firing — this\n is their production support workspace from day one, not a sandbox.\n- If they're migrating from another help desk, don't guess at content — actually fetch their existing\n pages before rewriting them into Plain's help center.\n","createdAt",["D",1788354775894],"branchVersion","branchId","3b7b1fb6-bbdc-49a4-9a99-33a7cf2f9a15","id","3c1c900e-c1e8-4f87-bbbe-df295b0d59ee","plain-agent-setup",["D",1788348742264],"deletedAt","legacyEnvVars","privacy","public","httpPrivacy","description","Live setup page + skill files for Plain's Claude Code onboarding","imageUrl","019bd3e5-3016-76dc-9fbe-33f578301ebf","pinnedFileId","01a061e4-3acb-7070-a926-90fc5b0aa181","pinPreview",true,"pinMigrated","screenshotVersion","likeCount",0,"orgId","019bd3e5-3016-76dc-9fbe-352b283c5ab0","tursoName","tursoHostname","tursoMeasuredAt","pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_96":95,"_103":99},"org",{"_96":95,"_97":-5,"_98":99,"_18":54,"_100":101,"_102":25},"branch",{"_13":85,"_32":86,"_42":41,"_87":43,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":44,"_94":95},"isOwned",39,"main","projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","jungfreud","handle","displayName","avatar","https://img.clerk.com/eyJ0eXBlIjoicHJveHkiLCJzcmMiOiJodHRwczovL2ltYWdlcy5jbGVyay5kZXYvb2F1dGhfZ2l0aHViL2ltZ18zOFNJVGp2cEpvRVM0UE5ONldxZWZGcmNOeDMifQ","tier","pro","canRestrictVals","profileImageUrl","branchName","","adoptOrgId",{"_42":43,"_32":44,"_37":221,"_46":-5,"_47":25,"_48":49,"_50":49,"_51":52,"_53":-5,"_18":54,"_55":56,"_57":58,"_59":-5,"_60":-5,"_61":62,"_63":64,"_65":-5,"_66":-5,"_67":-5,"_68":-5,"_69":70,"_71":70,"_72":73,"_74":73,"_75":73,"_76":70,"_77":70,"_78":222,"_80":223,"_82":224,"_84":25},"tree",[174,178,179,180,181],"files",[174,175,176,177,178,179,180,181],"counts",{"_164":62,"_165":155,"_166":62,"_167":168,"_169":170},"contents",[126,127,128,129,130],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_42":159,"_32":49,"_30":160,"_132":-5,"_40":41,"_39":155,"_133":58,"_37":161,"_13":62,"_33":162,"_34":-5,"_24":25,"_136":-5,"_27":163},{"_42":152,"_32":153,"_30":154,"_132":-5,"_40":41,"_39":155,"_133":58,"_37":156,"_13":62,"_33":20,"_34":157,"_24":25,"_136":-5,"_27":158},{"_42":145,"_32":146,"_30":56,"_132":-5,"_40":41,"_39":147,"_133":25,"_37":148,"_13":135,"_33":149,"_34":150,"_24":25,"_136":44,"_27":151},{"_42":138,"_32":139,"_30":140,"_132":-5,"_40":41,"_39":141,"_133":25,"_37":142,"_13":62,"_33":20,"_34":143,"_24":25,"_136":-5,"_27":144},{"_42":131,"_32":28,"_30":31,"_132":-5,"_40":41,"_39":14,"_133":25,"_37":134,"_13":135,"_33":20,"_34":36,"_24":25,"_136":-5,"_27":137},"4cc7aa2d-c7fb-4bbe-bf03-32b5908c1805","parentId","latest",["D",1788354775894],2,"label",[28],"5a2604f6-93b7-496d-ade9-ece1f3331404","reference.md","4f726ce8-a6c2-11f1-9a6d-1607ee4eb77e",3,["D",1788348891177],"# Plain GraphQL setup reference\n\nCleansed from Plain's live schema (`https://core-api.uk.plain.com/graphql/v1/schema.graphql`, ~19k lines,\n~440 mutations). This file lists only the mutations that matter for a first-time workspace setup, with\ntheir exact input fields, grouped in the order you'd actually run them. Everything here was read directly\noff the schema — no invented field names.\n\n**Endpoint:** `https://core-api.uk.plain.com/graphql/v1`\n**Auth:** `Authorization: Bearer plainApiKey_xxx`\n**Every mutation** takes a single `input` object and returns an `Output` type with the result plus an\noptional `error { message code }` — always check `error` before trusting the result.\n\nThe customer's \"setup key\" is a machine user + scoped API key created by a human in\nSettings → Machine Users (this is the one thing that can't be bootstrapped via API — you need a key to\ncall the API, so the first key is always made in the UI). Ask them to grant broad permissions for setup\n(or just use an Admin-scoped key) since almost everything below needs `*:create`/`*:update` on its area.\n\n**Never have the customer paste this key into the chat.** See `skill.md`'s \"Turn: handing you the key\nsafely\" — reference it as an environment variable they set themselves in a terminal, and never echo or\nprint the value.\n\n---\n\n## 0. Order of operations\n\nRespect these dependencies — calling things out of order will fail or leave orphaned config:\n\n1. Tiers (customer segments) — needed before SLAs and before tenants can be tiered\n2. SLAs — need a `tierId`\n3. Business hours — independent, but SLAs reference `useBusinessHoursOnly`\n4. Label Types — needed before thread fields that depend on labels, workflows that filter on labels, and SLA label filters\n5. Tenant Field Schemas — independent, but plan before creating tenants so fields exist\n6. Thread Field Schemas — independent, may reference label types via `dependsOnLabelTypeIds`\n7. Escalation Paths — reference label types and users\n8. Workflows / Workflow Rules — reference labels, fields, escalation paths — do these last of the \"routing\" group\n9. Saved (custom) Views — reference labels/fields, so do after those exist\n10. Help Center + Article Groups + Articles — independent, do any time\n11. Knowledge Sources (Ari) — can point at the Help Center you just built, or an external sitemap\n12. Sidekick settings / custom skills / MCP servers — independent\n13. Webhook Targets — independent\n14. Invite teammates + assign roles — can happen any time, but do it once roles/tiers exist if you want to seat people directly into tier membership\n15. Tenants (customer/account records) — once field schemas exist, backfill via `upsertTenant` + `upsertTenantField`\n\n---\n\n## 1. Tiers (customer segments)\n\n```graphql\nmutation {\n createTier(input: {\n name: \"Enterprise\"\n externalId: \"enterprise\"\n color: \"#5B5FEF\"\n defaultThreadPriority: 1 # 0=urgent 1=high 2=normal 3=low\n memberIdentifiers: [] # [{ companyId } | { tenantId }] to seed membership now\n isDefault: false # exactly one tier may be true\n }) { tier { id } error { message } }\n}\n```\n\nTo add members later: `addMembersToTier(input: { tierIdentifier: { tierId | externalId }, memberIdentifiers: [{ companyId } | { tenantId }] })`.\n\n## 2. SLAs (per tier)\n\n```graphql\nmutation {\n createServiceLevelAgreement(input: {\n tierId: \"...\"\n serviceLevelAgreement: {\n firstResponseTimeMinutes: 60\n nextResponseTimeMinutes: 240\n threadPriorityFilter: [0, 1] # optional, defaults to all 4 priorities\n useBusinessHoursOnly: true\n breachActions: [] # [BreachActionInput!] — what to do on warn/breach\n }\n }) { serviceLevelAgreement { id } error { message } }\n}\n```\n\n## 3. Business hours\n\n```graphql\nmutation {\n syncBusinessHoursSlots(input: {\n slots: [\n { timezone: \"Europe/London\", weekday: MONDAY, opensAt: \"09:00\", closesAt: \"17:30\" }\n # ... one entry per open weekday\n ]\n }) { businessHoursSlots { id } error { message } }\n}\n```\n(`upsertBusinessHours` still exists but is deprecated in favor of this.)\n\n## 4. Label Types (ticket categories/reasons)\n\n```graphql\nmutation {\n createLabelType(input: {\n name: \"Billing\"\n icon: \"💳\"\n color: \"#22C55E\"\n type: DEFAULT # or TEAM for a team-scoped label\n description: \"Billing and invoicing questions\"\n externalId: \"billing\"\n isExcludedFromAi: false\n }) { labelType { id } error { message } }\n}\n```\nAlso: `updateLabelType`, `archiveLabelType`/`unarchiveLabelType` (archive, don't delete), `moveLabelType`\n(reorder/reparent). Plain can also suggest label types from historical data —\n`suggestedLabelTypes` query + `acceptSuggestedLabelTypes` mutation, useful if migrating from another\nhelp desk with existing ticket categories.\n\n## 5. Tenant Field Schemas (custom data per customer account)\n\n```graphql\nmutation {\n upsertTenantFieldSchema(input: {\n tenantFieldSchemas: [{\n source: \"api\" # new schemas must be \"api\"\n externalFieldId: \"arr\"\n label: \"ARR\"\n type: NUMBER_TYPE # STRING_TYPE | NUMBER_TYPE | BOOLEAN_TYPE | STRING_ARRAY | DATETIME_TYPE | USER_REFERENCE_TYPE\n options: [] # for enum-like string fields\n isVisible: true\n order: 0\n }]\n }) { tenantFieldSchemas { id } error { message } }\n}\n```\nSetting a value: `upsertTenantField(input: { tenantFieldIdentifier: {...}, type: ..., stringValue/numberValue/booleanValue/arrayValue/dateValue/userReferenceValues: ... })` — set only the one value field matching `type`.\n\n## 6. Thread Field Schemas (custom data per ticket)\n\n```graphql\nmutation {\n createThreadFieldSchema(input: {\n label: \"Resolution reason\"\n key: \"resolution_reason\" # ^[a-z0-9_]+$, immutable after creation\n description: \"Why this ticket was closed\"\n order: 0\n type: ENUM # STRING | BOOL | ENUM | NUMBER | CURRENCY | DATE\n enumValues: [\"fixed\", \"wontfix\", \"duplicate\", \"user_error\"]\n isRequired: false\n isAiAutoFillEnabled: true # let Ari fill it from the conversation\n isAvailableToAgents: true\n isClientReadonly: false\n dependsOnLabelTypeIds: [] # only show this field on threads with these labels\n }) { threadFieldSchema { id } error { message } }\n}\n```\nAlso: `updateThreadFieldSchema`, `deleteThreadFieldSchema`, `reorderThreadFieldSchemas`, and setting values on a thread with `upsertThreadField` / `bulkUpsertThreadFields`.\n\n## 7. Escalation Paths\n\n```graphql\nmutation {\n createEscalationPath(input: {\n name: \"Billing escalation\"\n description: \"Escalate unresolved billing issues after 24h\"\n steps: [\n { type: ASSIGN_USER, userId: \"...\" }\n { type: ADD_LABEL, labelTypeId: \"...\" }\n ]\n }) { escalationPath { id } error { message } }\n}\n```\n\n## 8. Workflows (no-code automations) and Workflow Rules\n\nBoth are API-capable — contrary to \"UI only\" assumptions. The trigger/rule body is JSON-encoded, so it's\neasiest to build one example in the Plain UI first, then read it back via the `workflow`/`workflowRule`\nquery to see the exact JSON shape, and template from there for the rest.\n\n```graphql\nmutation {\n createWorkflow(input: {\n name: \"Route billing tickets\"\n trigger: \"{...JSON...}\" # see Workflow.trigger on an existing workflow for the shape\n }) { workflow { id } error { message } }\n}\nmutation {\n createWorkflowRule(input: { name: \"Auto-tag urgent\", payload: \"{...JSON...}\" }) {\n workflowRule { id } error { message }\n }\n}\n```\nThere's also a template gallery (`workflowTemplateGallery` / `workflowTemplate` queries,\n`exportWorkflowTemplate` mutation) worth checking before hand-rolling one from scratch.\n\n## 9. Saved (Custom) Views\n\n```graphql\nmutation {\n createSavedThreadsView(input: {\n name: \"My urgent billing tickets\"\n icon: \"🔥\"\n color: \"#EF4444\"\n threadsFilter: { } # SavedThreadsViewFilterInput — filter by labels, tier, status, assignee, etc.\n isHidden: false\n }) { savedThreadsView { id } error { message } }\n}\n```\n\n## 10. Help Center migration\n\n```graphql\nmutation { createHelpCenter(input: {\n publicName: \"Acme Help Center\"\n internalName: \"acme-help-center\"\n type: PUBLIC # PUBLIC | PRIVATE | INTERNAL\n description: \"...\"\n subdomain: \"acme\"\n isChatEnabled: true\n isCustomerFacingAiEnabled: true # let Ari answer directly on the help center\n}) { helpCenter { id } error { message } } }\n\nmutation { createHelpCenterArticleGroup(input: {\n helpCenterId: \"...\"\n name: \"Getting started\"\n parentHelpCenterArticleGroupId: null\n}) { helpCenterArticleGroup { id } error { message } } }\n\nmutation { upsertHelpCenterArticle(input: {\n helpCenterId: \"...\"\n helpCenterArticleGroupId: \"...\"\n title: \"How to reset your password\"\n contentHtml: \"

...

\"\n status: PUBLISHED\n slug: \"reset-password\"\n}) { helpCenterArticle { id } error { message } } }\n```\n`generateHelpCenterArticle` also exists (AI-drafts an article from a prompt) — useful when reformatting\nscraped content rather than pasting it verbatim. For bulk migration from an existing docs site: fetch each\npage (WebFetch/crawl), convert to clean HTML, and loop `upsertHelpCenterArticle` per page, grouping by the\nsite's existing nav structure into article groups first.\n\n## 11. Ari knowledge sources\n\n```graphql\nmutation {\n createKnowledgeSource(input: {\n url: \"https://acme.com/sitemap.xml\"\n type: SITEMAP # SITEMAP (crawls every URL in the sitemap) | URL (single page)\n labelTypeIds: [] # optionally scope this source to specific ticket categories\n }) { knowledgeSource { id } error { message } }\n}\n```\nA help center you create is auto-indexed — you don't need a separate knowledge source for it. Use\n`createKnowledgeSource` for anything external: an existing docs site, a changelog, a status page, etc.\nFind the sitemap yourself via `WebFetch /sitemap.xml` (or `/robots.txt`, which usually points at it)\nbefore asking the customer to hunt for it.\n\n## 12. Sidekick (Plain's AI agent)\n\n```graphql\nmutation { updateSidekickSettings(input: { customPrompt: \"Always mention our 30-day refund policy.\" }) { error { message } } }\n\nmutation { createSidekickCustomSkill(input: {\n displayName: \"Check subscription status\"\n description: \"Looks up a customer's plan and billing status\"\n instructions: \"...\"\n}) { sidekickCustomSkill { id } error { message } } }\n\nmutation { createSidekickMcpServer(input: {\n name: \"Stripe\"\n url: \"https://mcp.stripe.com\"\n operatingInstructions: \"Use for billing/subscription lookups only.\"\n # omit apiKeyAuth for OAuth servers (default); provide it to register an API-key server\n}) { sidekickMcpServer { id } error { message } } }\n```\nMCP servers using OAuth still need the human to click through the OAuth consent screen in the UI after\n`createSidekickMcpServer` creates the shell — the API can provision the connector but not complete\nthird-party OAuth handshakes headlessly. API-key-auth MCP servers can be fully wired via API (the actual\nsecret is entered client-side and vaulted, never sent through this mutation).\n\n## 13. Webhook Targets\n\n```graphql\nmutation {\n createWebhookTarget(input: {\n url: \"https://acme.com/plain-webhook\"\n eventSubscriptions: [{ eventType: \"thread.sla_status_transitioned\" }]\n isEnabled: true\n description: \"Notify our internal ops channel on SLA breach\"\n }) { webhookTarget { id } error { message } }\n}\n```\nCheck `subscriptionEventTypes` query for the full live list of event type strings before hardcoding one.\n\n## 14. Team members and roles\n\n```graphql\nmutation { inviteUserToWorkspace(input: { email: \"jane@acme.com\", roleKey: SUPPORT }) { error { message } } }\n```\n`roleKey` is one of `OWNER | ADMIN | SUPPORT | VIEWER | NONE`, or pass `customRoleId` for a role made with\n`createCustomRole` + `upsertRoleScopes`. Existing users: `assignRolesToUser(input: { userId, roleKey | customRoleId })`.\n\n## 15. Tenants (customer/account records)\n\n```graphql\nmutation { upsertTenant(input: {\n identifier: { externalId: \"acme-inc\" }\n name: \"Acme Inc\"\n externalId: \"acme-inc\"\n primaryDomain: { value: \"acme.com\" }\n isDomainAutoJoinEnabled: { value: true }\n}) { tenant { id } error { message } } }\n```\nThen set custom fields with `upsertTenantField`, and tier it with `updateTenantTier`.\n\n---\n\n## Permission scopes to grant the setup key\n\nPulled from the `Requires the 'x:y' permission` notes on the schema itself (not all mutations document\none — where none is listed, it's covered by having the general area's `create`/`edit` scope). Grant these\nwhen creating the API key in Settings → Machine Users → Add API key. If in doubt, granting the full Admin\nrole's scopes is simplest for a one-time setup key — just don't leave a broad key lying around afterward\n(see \"After setup\" below).\n\n| Area | Scopes |\n|---|---|\n| Tiers | `tier:create`, `tier:read`, `tier:update` |\n| SLAs | `serviceLevelAgreement:create`, `serviceLevelAgreement:edit` |\n| Business hours | `businessHours:edit`, `businessHours:read` |\n| Labels | `labelType:create`, `labelType:edit`, `label:create`, `suggestedLabelType:read` |\n| Tenant fields | `tenantFieldSchema:create`, `tenantFieldSchema:edit` |\n| Tenants | `tenant:create`, `tenant:read` |\n| Thread fields | `threadFieldSchema:create`, `threadFieldSchema:edit`, `threadField:create` |\n| Escalation paths | `escalationPath:create`, `escalationPath:edit`, `escalationPath:read` |\n| Workflows | no explicit scope documented on `createWorkflow`/`createWorkflowRule` — covered by Admin; `workflowRule:read` confirmed for reading rules back |\n| Saved views | `savedThreadsView:create` |\n| Help Center | `helpCenter:edit` (covers create/update/delete of the help center, articles, and article groups — note `helpCenter:read` queries are blocked for machine users on a couple of endpoints, so verify by re-listing rather than reading back through those) |\n| Ari knowledge sources | no explicit scope documented — covered by Admin |\n| Sidekick settings/skills/MCP servers | `workspaceSlackSidekickIntegration:create/update/delete` (Slack-specific config); custom skills and MCP server mutations have no explicit scope documented — covered by Admin |\n| Webhooks | `webhookTarget:create`, `webhookTarget:edit`, `webhookTarget:read` |\n| Invites & roles | `roles:read`, `roles:assign`, `roles:create`, `roles:edit` (no explicit scope documented on `inviteUserToWorkspace` itself — covered by Admin) |\n| Customer groups | `customerGroup:create`, `customerGroup:edit` (only if you use these) |\n| API keys / machine users | `apiKey:create`, `apiKey:edit`, `machineUser:create`, `machineUser:edit` (only needed if the setup flow itself provisions further keys) |\n| Sanity check | `permission:read` — lets you call `myPermissions` to confirm what the key can actually do before you start |\n\nA handful of areas in the schema (Sidekick custom skills/MCP servers, Ari knowledge sources, Workflows)\ndon't carry an explicit `Requires the 'x:y' permission` doc comment at all — that's the schema's own gap,\nnot this reference's. Confirm scope needs for those by running `myPermissions` after your first attempt at\neach, or just grant Admin for the session.\n\n**After setup:** this key can create tiers, invite teammates, and publish public help center content —\ntreat it as a privileged credential. Once the workspace is configured, either delete the machine user\n(`deleteMachineUser`) or narrow its API key's permissions down to whatever ongoing automation actually\nneeds, rather than leaving a broad setup key active indefinitely.\n\n## Confirmed UI-only (no mutation exists in the schema)\n\n- **Personal notification preferences** — per-user notification settings. `updateInternalNotifications`\n only marks existing notifications read/archived; it does not set preferences. UI: avatar → Preferences.\n- **OAuth completion for channel integrations** — Slack/MS Teams/Discord/email forwarding connectors have\n `create*Integration` mutations that provision the shell, but the actual OAuth consent/DNS verification\n step (`startServiceAuthorization` → browser redirect, or `verifyWorkspaceEmailForwardingSettings` DNS\n check) needs a human in the loop. Treat these as \"API can start it, human must finish it in browser.\"\n- **Chat widget install snippet placement** — generating the embed script is API/UI-driven, but pasting it\n into the customer's own site is inherently a manual step outside Plain entirely.\n\nEverything else above has a real, confirmed mutation — don't assume something is UI-only without checking\nthis file or the live schema at the URL above first.\n",[139],"2793764e-f599-4dde-8a08-5ded28a5ede0","index.tsx",7,["D",1788352189431],"http","import { Hono } from \"npm:hono@4\";\nimport { parseVal, readFile } from \"https://esm.town/v/std/utils/index.ts\";\n\nconst app = new Hono();\n\napp.get(\"/\", async (c) => {\n const html = await readFile(\"/public/index.html\", import.meta.url);\n return c.html(html);\n});\n\napp.get(\"/skill.md\", async (c) => {\n const md = await readFile(\"/skill.md\", import.meta.url);\n return c.text(md, 200, {\n \"content-type\": \"text/markdown; charset=utf-8\",\n \"content-disposition\": 'inline; filename=\"skill.md\"',\n });\n});\n\napp.get(\"/reference.md\", async (c) => {\n const md = await readFile(\"/reference.md\", import.meta.url);\n return c.text(md, 200, {\n \"content-type\": \"text/markdown; charset=utf-8\",\n \"content-disposition\": 'inline; filename=\"reference.md\"',\n });\n});\n\n// View source on Val Town\napp.get(\"/source\", (c) => c.redirect(parseVal().links.self.val));\n\n// Unwrap and rethrow Hono errors as the original error\napp.onError((err) => Promise.reject(err));\n\nexport default app.fetch;\n",[146],"67a4f1c1-3637-4404-9e16-6d13683b3dae","README.md","01a061e4-3acb-7070-a926-8c4f90b26c5e",1,["D",1788348742264],"# hono-jsx-starter\n\nA minimal [Hono](https://hono.dev) + Hono JSX starter for Val Town.\nServer-rendered HTML, no build step, no React.\n\n## Picking a starter\n\n| Starter | When to pick it |\n| --- | --- |\n| [`basic-html-starter`](https://www.val.town/x/templates/basic-html-starter) | Static HTML pages. Sprinkle of vanilla JS. No server-side rendering. |\n| **[`hono-jsx-starter`](https://www.val.town/x/templates/hono-jsx-starter)** *(you're here)* | Dynamic server-rendered HTML with JSX. API routes. No React, no SPA. |\n| [`react-hono-starter`](https://www.val.town/x/templates/react-hono-starter) | Client-side React SPA with a Hono API backend. |\n\n## What's here\n\n```\nindex.tsx Hono app, Layout, routes\npublic/\n favicon.svg Static asset\n counter.ts Tiny client-side script\n```\n\nThe whole app fits in one file. As you grow it, the natural next moves are:\n\n- Pull `Layout` into its own `.tsx` file once you have 3+ pages.\n- Split routes with `app.route(\"/api\", api)` if `/api/*` grows.\n- Add more files under `public/` — they're served by a single\n `app.get(\"/public/*\", ...)` route.\n\n## Patterns worth knowing\n\n**JSX pragma.** Every `.tsx` file that uses JSX needs this at the top:\n\n```tsx\n/** @jsxImportSource npm:hono@4/jsx */\n```\n\n**Server state.** The counter on `/` is `let count = 0` at module scope. It\nlives in memory on the Val Town server and survives across requests — but resets\nwhenever the val restarts (deploys, idle timeouts, etc.). For persistent state,\nswap it for [`std/sqlite`](https://www.val.town/x/std/sqlite) or\n[`std/blob`](https://www.val.town/x/std/blob).\n\n**API routes.** The `Increment` button POSTs to `/api/increment`, which returns\nJSON. Mix server-rendered pages and JSON endpoints in the same Hono app:\n\n```ts\napp.post(\"/api/increment\", (c) => c.json({ count: ++count }));\n```\n\n**Static files.** `serveFile` reads the file by path and serves it with the\nright content-type. `.ts` files are transpiled to JS on request by Val Town — so\nyou can write `public/counter.ts` and reference it as\n`\n\n\n\n",[],[49,196],"dfa17abd-085c-45c1-81d7-cd10c11b9b60","favicon.svg","01a061e4-3acb-7070-a926-842f4e54d674",["D",1788348742264],"\n",[],[49,204],"70c7bc19-dc6c-4ab8-b78f-c08042ad49f0","counter.ts","01a061e4-3acb-7070-a926-8362bdc08d67",["D",1788348742264],"script","const count = document.getElementById(\"count\")!;\nconst button = document.getElementById(\"increment\")!;\n\nbutton.addEventListener(\"click\", async () => {\n const res = await fetch(\"/api/increment\", { method: \"POST\" });\n const data = await res.json();\n count.textContent = String(data.count);\n});\n",[],[49,211],["D",1788348742264],[175,176,177],[49],["D",1788348742264],{"_96":95,"_103":99},{"_96":95,"_97":-5,"_98":99,"_18":54,"_100":101,"_102":25},{"_13":85,"_32":86,"_42":41,"_87":43,"_88":-5,"_89":-5,"_90":-5,"_91":-5,"_92":-5,"_93":44,"_94":95},"ctx",{"_78":-5,"_123":258,"_259":260,"_261":262,"_263":25,"_264":25,"_265":25,"_266":58,"_267":-5,"_268":-7,"_269":-7,"_270":62,"_271":25,"_272":25,"_273":-5,"_274":25,"_275":25,"_276":25,"_277":-5},"ENV",{"_229":230,"_231":232,"_233":86,"_234":235,"_236":237,"_238":239,"_240":241,"_242":243,"_244":245,"_246":247,"_248":249,"_250":251,"_252":253,"_254":255,"_256":257},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Diff · v10