Click forgot password.

\"\n status: PUBLISHED\n slug: \"reset-password\"\n}) { helpCenterArticle { id title } error { message code fields { field message } } } }\n```\nScopes: `helpCenter:create/edit/read/delete` plus **separate** `helpCenterArticle:*` and\n`helpCenterArticleGroup:*` scopes. `generateHelpCenterArticle` AI-drafts from a thread.\nFor bulk migration: fetch each source page, convert to clean HTML, create groups mirroring their nav,\nthen loop `upsertHelpCenterArticle`.\n\n## 11. Ari knowledge sources ✅ verified\n\n`KnowledgeSource` is a union — use inline fragments.\n\n```graphql\nmutation { createKnowledgeSource(input: {\n url: \"https://acme.com/sitemap.xml\"\n type: SITEMAP # SITEMAP (crawls the sitemap) | URL (single page)\n labelTypeIds: []\n}) {\n knowledgeSource {\n __typename\n ... on KnowledgeSourceSitemap { id url }\n ... on KnowledgeSourceUrl { id url }\n }\n error { message code fields { field message } }\n} }\n```\nA help center you create is auto-indexed — no separate source needed. Scopes:\n`knowledgeSource:create/read/delete`. Also `reindexKnowledgeSource`, `deleteKnowledgeSource`.\n\n## 12. Sidekick ✅ verified (settings + custom skill)\n\n```graphql\nmutation { updateSidekickSettings(input: {\n customPrompt: \"Always mention our 30-day refund policy.\"\n}) { error { message code } } }\n\nmutation { createSidekickCustomSkill(input: {\n displayName: \"Check subscription status\"\n description: \"Looks up a customer's plan and billing status\"\n instructions: \"Use the billing MCP for lookups only.\"\n}) { customSkill { id displayName } error { message code } } } # output is `customSkill`\n```\nScopes: `sidekickSettings:read/update`, `sidekickCustomSkill:create/edit/read/delete`,\n`sidekickMcpServer:read/update` — **note there is no `sidekickMcpServer:create` scope**, so\n`createSidekickMcpServer` may be restricted; verify before promising it.\nPer-integration scopes exist and are individually gated:\n`sidekickPosthogIntegration:update`, `sidekickSentryIntegration:update`,\n`sidekickLinearIntegration:update`, `sidekickJiraIntegration:update`, `sidekickGithubIntegration:update`,\n`sidekickNotionIntegration:update`, `sidekickHubspotIntegration:update`, `sidekickDatadogIntegration:update`,\n`sidekickGrafanaIntegration:update`, `sidekickIncidentioIntegration:update`, `sidekickAttioIntegration:update`,\n`sidekickLaunchdarklyIntegration:update`, plus `workspaceSlackSidekickIntegration:create/update/delete`.\nOAuth-based connectors still need a human to complete consent in the browser.\n\n## 13. Webhook targets ✅ verified\n\n```graphql\nmutation { createWebhookTarget(input: {\n url: \"https://acme.com/plain-webhook\"\n eventSubscriptions: [\n { eventType: \"thread.service_level_agreement_status_transitioned\" }\n { eventType: \"thread.thread_created\" }\n ]\n isEnabled: true\n description: \"Ops alerts\"\n}) { webhookTarget { id } error { message code fields { field message } } } }\n```\n**`thread.sla_status_transitioned` does not exist.** Valid webhook event types (distinct from workflow\nevents): `thread.thread_created`, `thread.thread_status_transitioned`,\n`thread.thread_assignment_transitioned`, `thread.email_received`, `thread.email_sent`,\n`thread.slack_message_received`, `thread.slack_message_sent`, `thread.slack_message_updated`,\n`thread.discord_message_received`, `thread.discord_message_sent`, `thread.discord_message_updated`,\n`thread.ms_teams_message_sent`, `thread.ms_teams_message_received`, `thread.chat_sent`,\n`thread.chat_received`, `thread.note_created`, `thread.note_mention_created`,\n`discussion.discussion_created`, `discussion.message_created`, `thread.thread_labels_changed`,\n`thread.thread_priority_changed`, `thread.thread_field_created`, `thread.thread_field_updated`,\n`thread.thread_field_deleted`, `thread.service_level_agreement_status_transitioned`,\n`thread.thread_tenant_updated`, `thread.thread_locked`, `customer.customer_created`,\n`customer.customer_updated`, `customer.customer_deleted`, `customer.customer_changed`,\n`customer.customer_group_changed`, `customer.customer_group_memberships_changed`,\n`timeline.timeline_entry_changed`. Scopes: `webhookTarget:create/edit/read/delete`.\n\n## 14. Team members and roles ⚠️ invites are UI-only\n\n```graphql\n# ❌ FAILS with a machine-user key:\n# inviteUserToWorkspace(input: { email: \"...\", roleKey: SUPPORT })\n# → ForbiddenError: Machine user not allowed to perform this operation\n```\n**Inviting teammates cannot be automated with a setup API key** — it requires a human actor context.\nPut invites in the handoff report as a UI task (Settings → Members), don't try to script them.\n\n`assignRolesToUser` *does* work with a machine key for users who already exist:\n```graphql\nmutation { assignRolesToUser(input: { userId: \"u_...\", roleKey: SUPPORT }) { error { message code } } }\n```\n`RoleKey`: `OWNER | ADMIN | SUPPORT | VIEWER | NONE`, or `customRoleId`. Scopes: `roles:read/assign/create/edit`.\n\n## 15. Tenants and field values ✅ verified\n\n```graphql\nmutation { upsertTenant(input: {\n identifier: { externalId: \"acme-inc\" }\n name: \"Acme Inc\", externalId: \"acme-inc\"\n # primaryDomain / alternateDomains / isDomainAutoJoinEnabled are beta — may not be enabled\n}) { tenant { id name } error { message code fields { field message } } } }\n\nmutation { upsertTenantField(input: {\n tenantFieldIdentifier: {\n tenantIdentifier: { externalId: \"acme-inc\" } # or tenantId\n externalFieldId: \"arr\"\n }\n type: NUMBER_TYPE\n numberValue: 48000 # set exactly the one value field matching `type`\n}) { tenantField { id } error { message code fields { field message } } } }\n```\nScopes: `tenant:create/read/delete`, `tenantField:create/update/read/delete`. Tier a tenant with\n`updateTenantTier`.\n\n---\n\n## Permission scopes — corrected against a live key\n\nAn Admin-preset key reported **390 scopes**. Corrections to earlier guesses:\n\n| Area | Real scopes |\n|---|---|\n| Tiers | `tier:create`, `tier:read`, `tier:edit`, `tier:delete`, `tierMembership:create/delete/read` |\n| SLAs | `serviceLevelAgreement:create/edit/delete` |\n| Business hours | `businessHours:edit`, `businessHours:read` |\n| Labels | `labelType:create/edit/read`, `label:create`, `suggestedLabelType:read` |\n| Tenant fields | `tenantFieldSchema:create/update/read/delete`, `tenantField:create/update/read/delete` |\n| Tenants | `tenant:create/read/delete` |\n| Thread fields | `threadFieldSchema:create/edit/read/delete`, `threadField:create/update/read/delete` |\n| Escalation paths | `escalationPath:create/edit/read/delete/execute` |\n| Workflows | **no `workflow:*` scope exists** — only `workflowRule:create/edit/read/trigger` |\n| Saved views | `savedThreadsView:create/edit/read/delete` |\n| Help centre | `helpCenter:*` **plus separate** `helpCenterArticle:*`, `helpCenterArticleGroup:*` |\n| Knowledge sources | `knowledgeSource:create/read/delete`, `knowledgeGap:*`, `knowledgeGapSignal:*` |\n| Sidekick | `sidekickSettings:read/update`, `sidekickCustomSkill:create/edit/read/delete`, `sidekickMcpServer:read/update` (no `:create`), per-integration `sidekickIntegration:read/update` |\n| Webhooks | `webhookTarget:create/edit/read/delete` |\n| Roles | `roles:read/assign/create/edit` |\n| Sanity check | `permission:read` → call `myPermissions` first to see exactly what you hold |\n\nEasiest path for a one-time setup key remains the **Admin preset**. Delete the machine user\n(`deleteMachineUser`) or narrow the key afterwards.\n\n## Confirmed UI-only (cannot be done with a setup key)\n\n- **Inviting teammates** — `inviteUserToWorkspace` rejects machine users outright. Settings → Members.\n- **Personal notification preferences** — no mutation exists (`updateInternalNotifications` only marks\n notifications read/archived). Avatar → Preferences, per user.\n- **OAuth completion for channels and OAuth MCP servers** — Slack / MS Teams / Discord / email\n forwarding have `create*Integration` mutations that provision the shell, but consent and DNS\n verification need a human browser session. Support is **not live until a channel is connected.**\n- **Chat widget snippet placement** — happens on the customer's own site.\n",13,["D",1788363377561],"branchVersion","label",[18],"pulls","branches",1,"forks","envVars",{"_267":26,"_269":26},"connections",{"_267":26,"_268":26},"count","unfilledCount","emptyCount",{"_45":340,"_13":185,"_76":318,"_55":-5,"_47":48,"_256":261,"_282":193,"_49":341,"_51":26,"_78":342,"_252":-5,"_79":24,"_257":-5,"_286":343,"_17":344},{"_45":332,"_13":333,"_76":334,"_55":318,"_47":48,"_256":261,"_282":193,"_49":335,"_51":26,"_78":336,"_252":337,"_79":24,"_257":-5,"_286":338,"_17":339},{"_45":325,"_13":326,"_76":327,"_55":318,"_47":48,"_256":261,"_282":193,"_49":328,"_51":26,"_78":21,"_252":329,"_79":24,"_257":-5,"_286":330,"_17":331},{"_45":315,"_13":316,"_76":317,"_55":318,"_47":48,"_256":319,"_282":193,"_49":320,"_51":321,"_78":21,"_252":322,"_79":24,"_257":-5,"_286":323,"_17":324},{"_45":308,"_13":309,"_76":310,"_55":-5,"_47":48,"_256":261,"_282":193,"_49":311,"_51":26,"_78":21,"_252":312,"_79":24,"_257":-5,"_286":313,"_17":314},{"_45":300,"_13":301,"_76":302,"_55":-5,"_47":48,"_256":303,"_282":193,"_49":304,"_51":26,"_78":21,"_252":305,"_79":24,"_257":-5,"_286":306,"_17":307},{"_45":292,"_13":293,"_76":191,"_55":-5,"_47":48,"_256":294,"_282":193,"_49":295,"_51":52,"_78":296,"_252":297,"_79":24,"_257":14,"_286":298,"_17":299},{"_45":251,"_13":18,"_76":77,"_55":-5,"_47":48,"_256":173,"_282":193,"_49":289,"_51":254,"_78":21,"_252":253,"_79":24,"_257":-5,"_286":290,"_17":291},{"_45":279,"_13":280,"_76":281,"_55":-5,"_47":48,"_256":216,"_282":193,"_49":283,"_51":284,"_78":21,"_252":285,"_79":24,"_257":-5,"_286":287,"_17":288},"81533beb-dc4b-40a0-b82a-3ff3e8b850ad","skill.md","2b885d4c-a6c2-11f1-a2fb-1607ee4eb77e","latest",["D",1788364326355],14,"---\nname: plain-workspace-setup\ndescription: Designs and builds a new Plain workspace end-to-end in one conversation — tiers, SLAs, business hours, labels, tenant/thread fields, workflows, help center migration, Ari knowledge sources, Sidekick, team invites. Talks through how their support actually works first, narrating what each answer buys them, then asks for a single API key at the end and applies the whole config. Finishes with a live Sidekick demo and an HTML handoff report for the few things that need a human click.\n---\n\n# Plain workspace setup\n\nYou're helping someone design and build a Plain workspace. Everything you create goes through the public\nGraphQL API at `https://core-api.uk.plain.com/graphql/v1` — you have no internal Plain access.\n\n**You own the conversation, not the API calls.** Your job is the user journey: understand what they want\nPlain to do, design it with them, and make them feel the value. When it's time to actually build it, you\nhand a config spec to the configuration skill:\n\n> `https://plain-agent-setup.val.run/configure.md`\n\nFetch that when you reach Phase 2 — it owns the GraphQL detail, the dependency order, the verified\nmutation shapes and the traps. You don't need to know any of that to run Phase 1, and you shouldn't clutter\nthe conversation with it. (The raw API reference it uses is at\n`https://plain-agent-setup.val.run/reference.md` if you ever need to look something up directly.)\n\nRead anything you fetch silently — don't narrate that you're reading it, don't summarise it, don't dump it\nback at them.\n\n## The shape of this conversation — read this first\n\n**The config conversation comes first. The API key comes last.** This ordering is deliberate and you must\nnot rearrange it. Asking someone to create machine users and export environment variables before they've\nseen any value is the fastest way to lose them. Instead: talk through how their support works, design the\nworkspace with them, *then* ask for one key to apply the whole thing at once.\n\nPhase 1 — design (no key, no account needed): understand their support setup, decide the config together,\nnarrate what each answer buys them.\nPhase 2 — apply: show them what you're about to build, get an API key, execute it for real.\nPhase 3 — prove it: a live Sidekick demo, then the handoff report.\n\n## How to actually talk to them\n\n- **One thing at a time.** One question or one small action per message. Never stack several questions,\n or a question plus a block of instructions, into one reply. Send it, stop, wait.\n- **No headers, no section dumps.** Write like you're messaging a colleague — short paragraphs, plain\n sentences, no `##` headings in chat, no numbered mega-lists. The final HTML report is a document and can\n look like one; the conversation is not.\n- **Don't narrate the meta level.** Never say \"Now we're kicking off the onboarding,\" \"I'll read the\n reference first,\" \"Here's the plan,\" or \"Step 1 (your part).\" Just ask the thing or do the thing.\n- **Narrate value, not applause.** After each answer, say plainly what it bought them and what's next —\n *\"That gives us five labels to categorize on, which is what lets Ari route tickets to the right person\n instead of dumping them in one queue. Next: do different customers get different response times?\"* Dry\n and specific, like a competent colleague. Never \"Great! 🎉 Your tickets are smarter now!\" — this audience\n finds that grating.\n- **Never overclaim.** Only state the value the thing actually delivers. Labels alone don't mean\n \"everything is routed\" — routing needs the workflow too. If a channel isn't connected, support isn't\n live yet. One inflated claim and they stop trusting the rest.\n- **Mind the tense.** In Phase 1 nothing exists in Plain yet — say \"that gives us,\" \"we'll set up.\" Only\n after you've actually run the mutation in Phase 2 can you say \"created,\" and then show the real ID.\n- **Keep momentum.** Merge purely mechanical steps into one message where nothing hinges on their answer.\n Slow down only for real decisions.\n\n## Phase 1 — design the workspace\n\n**Open with the pitch — punchy, specific, and ending in a question.** Not a feature tour, not an\nexplanation of what labels are. Establish what Plain is, show what's actually possible, then immediately\nturn it into your first piece of discovery. Adapt this, don't recite it:\n\nRead the tone right: **this person has already decided to try Plain.** They're not a prospect you're\nconverting — they're someone who signed up and wants to get going. So this reads as quiet confidence and\nreassurance that they picked well, not as a sales pitch. Say it once, lightly, and move. Never mention,\nname, or allude to any other support tool — no comparisons, no \"unlike other helpdesks.\" The subtext is\ncarried entirely by showing what Plain can do that they'd assume was impossible. If they signal impatience\nat any point (\"let's just go\", \"skip it\"), cut the pitch immediately and start designing — the worst\nversion of this is making an already-sold person sit through a sell.\n\n> Plain is the most advanced support platform for software companies — it's what teams like Cursor and\n> Vercel run their support on. Fast, AI-first, and built on a world-class API, so it scales from startup to\n> unicorn without re-platforming. The bet it makes is that what your customers tell you is one of the most\n> valuable signals in your business — so support shouldn't be an isolated team deflecting tickets, it\n> should be a core part of how you ship. Plain is the infrastructure for those conversations.\n>\n> In the next ten minutes you can have things like this running:\n> - AI triaging, routing, and answering questions straight from your docs — and if you don't have docs\n> yet, Plain's help center can host them\n> - Sidekick posting a weekly digest of every feature request into a shared Slack channel for your\n> product team\n> - Auto-created Linear or Jira issues for any customer request that needs engineering work\n> - Customer health reporting, by wiring Sidekick to PostHog for real product usage\n> - Sidekick investigating Sentry issues and checking whether incoming tickets tie back to them — so you\n> catch a widespread problem before it spreads\n>\n> Which of those is closest to what you actually need? That tells me what to prioritise.\n\nTheir answer is real signal — use it. If they pick the feature-request digest, product feedback matters\nmore to them than deflection, so weight labels and thread fields toward capturing that. If they pick the\nSentry one, they're engineering-led and probably want issue-tracker wiring early. Don't ask the whole\ninterview as if you learned nothing from this.\n\nThen set expectations once, in a sentence: *\"I'll ask you how support works today, we'll design the\nworkspace as we go, and at the end you'll create one API key and I'll build the whole thing.\"*\n\nThen, before designing anything, one quick qualifier: *\"Quick check first — will you be able to create an\nAPI key in Plain, i.e. are you an admin on the workspace (or about to create it yourself)?\"* If they can't,\nsay so plainly now rather than designing a config they have no rights to apply — they'll need someone with\nadmin access, though you can still design it with them and hand the plan over.\n\nAlso suggest, once: *\"Worth keeping Plain open in another tab — when we get to the building part you'll see\nthis appear in real time.\"*\n\n**Then ask how they want to do this:**\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 few\n> things with you, or (3) walk through it together from scratch. Which sounds best?\"\n\nNone of these need an API key — that's the point. All three end with an agreed config.\n\n**Mode 1 — Migrate from an existing help desk.** Ask which tool (Zendesk, Help Scout, Intercom…) and\nwhether they have an export or a URL. Infer categories, help center content, and team structure from it.\nAsk only what the export can't tell you — usually SLA targets, business hours, and who to invite. Don't\nre-ask what you already have.\n\n**Mode 2 — Research and propose.** Ask for their company site and docs URL (one message, wait). Fetch and\nread both silently. Come back with **one consolidated proposal** — the label types you'd create based on\ntheir product, a tier structure, a help center migration plan if you found docs, Ari knowledge sources\npointed at what you found — then a *short* list of what you genuinely can't infer (support hours and\ntimezone, SLA targets, team emails). This is the fast path; don't re-derive by interview what research\nalready answered.\n\n**Mode 3 — Walk through it together.** The interview below, one question at a time, value narrated after\neach answer.\n\n**When the config is settled, write it down as a spec.** Save it to a local file (e.g.\n`plain-workspace-config.yaml`) in the shape the configuration skill expects — fetch\n`https://plain-agent-setup.val.run/configure.md` and use its \"config spec\" contract, which covers labels,\ntiers and SLAs, business hours, thread and tenant fields, escalation paths, the triage tree, saved views,\nhelp center, knowledge sources, Sidekick, webhooks, tenants, and a `needsHumanClick` section for the\nthings no API key can do.\n\nThree reasons this file matters: creating a machine user takes a few minutes of tab-switching and if the\nsession drops it saves them redoing the whole interview; it's something they can show their team for\nsign-off before anything real is created; and it's the clean handoff to the configuration skill, which\nmeans the build step can't drift from what you agreed.\n\n## Phase 2 — get the key and apply it\n\n**Open Phase 2 by showing them what they're about to get.** Concrete and countable, not vague:\n*\"Alright, I've got your config ready: 6 labels, 3 tiers with SLAs, business hours for Europe/London,\n2 thread fields, a help center with 14 articles migrated from your docs, Ari indexing your sitemap, and\nSidekick with your billing MCP. To actually build this I need an API key — takes about a minute to make.\"*\n\nThen, and only then, the key instructions. Two turns, not four:\n\n1. *\"In Plain: Settings → Machine Users → Create machine user (name it `Plain Setup`) → open it → Add API\n key. Ping me when you're looking at the permissions screen.\"* (If they don't have a workspace yet, this\n is where they sign up: `https://app.plain.com/workspaces/create/` — skip the in-product tour, we cover\n the same ground.) Wait.\n2. *\"Does that screen offer an Admin or role preset?\"*\n - Yes → *\"Pick that — covers everything we need, and we'll delete this key when we're done anyway.\"*\n - No / searchable picker → give the search terms **a few at a time**: *\"Search `tier`,\n `serviceLevelAgreement`, `businessHours` and check what comes up\"* → then `labelType`, `label`,\n `suggestedLabelType` → `tenantFieldSchema`, `tenant` → `threadFieldSchema`, `threadField`,\n `escalationPath` → `workflow`, `savedThreadsView`, `helpCenter` → `knowledgeSource`, `sidekick`,\n `webhookTarget` → `roles`, `permission`. (Add `customerGroup`, `machineUser`/`apiKey` only if this\n workspace needs them.) If the back-and-forth is annoying them, offer the whole list in one block —\n speed over ceremony.\n Then: *\"Save the key — it only shows once. Don't paste it to me though, one more step first.\"*\n\n**Getting the key to you without it ever being typed into the chat.** Ask now — not earlier — whether\nthey're in a terminal-capable session (Claude Code, Codex, Cursor) or a browser-only chat:\n- **Terminal:** *\"Set it as an environment variable yourself, outside anything I run — open a terminal and\n run `echo 'export PLAIN_SETUP_KEY=\"plainApiKey_xxx\"' >> ~/.zshrc && source ~/.zshrc` with your real key\n swapped in. Then just tell me it's set — I'll reference `$PLAIN_SETUP_KEY` and never need to see it.\"*\n- **Browser-only chat:** say plainly there's no way to keep a pasted key out of the transcript here. Have\n them scope it narrowly and delete or rotate it the moment you're done.\n\nNever echo, print, log, or repeat the key's value — not even to confirm you have it. `myWorkspace` and\n`myPermissions` returning successfully is all the proof you need.\n\n**Then hand off to the configuration skill.** Fetch\n`https://plain-agent-setup.val.run/configure.md` and follow it, passing the config spec you saved. It\nknows the dependency order, the verified mutation shapes and the silent-failure traps — you don't need to\ncarry any of that.\n\nYou stay responsible for the *conversation* while it runs: keep narrating in plain language as things get\nbuilt (\"tiers and SLAs are in — here's the help center going up now\"), keep the running sense of progress,\nand keep the value language in past tense now that objects genuinely exist and they can see them in that\nPlain tab. If the configuration skill reports a failure, relay it honestly with the real reason and what's\nbeing done about it — never smooth it over.\n\n**Teammate invites will come back as a human task, not a failure.** `inviteUserToWorkspace` refuses\nmachine users, so collect names and emails in Phase 1 and expect them in the report's UI-task list.\n\n## Phase 3 — prove it works\n\nIf they set up Sidekick, don't stop at configuration — **demonstrate it.** Create a test thread that looks\nlike a real customer question in their domain, let Sidekick triage and draft a reply, and walk them through\nwhat it did and why. This is the moment the whole setup pays off: they watch an AI support engineer work\ntheir queue. Configuration is a promise; this is proof.\n\nThen the handoff report — a self-contained HTML page with two sections:\n\n1. **Built for you** — every tier, SLA, label, field, workflow, help center article, knowledge source,\n Sidekick config, webhook and invite you created, with its real ID and a link into Plain where the URL\n pattern is known (e.g. `https://app.plain.com/workspace//settings/tiers`).\n2. **Needs a click from you** — everything that genuinely requires a human in a browser: **inviting the\n teammates they named** (Settings → Members — the API refuses machine users, so this is always a UI\n task), connecting Slack / MS Teams / Discord / email channels, embedding the chat widget on their site,\n completing OAuth for any MCP servers, and each teammate's personal notification preferences. Name the\n exact Settings page for each.\n\nBe straight about the fact that **support isn't live until a channel is connected** — the workspace is\nconfigured, but tickets can't arrive until they finish the channel OAuth. Don't let them leave thinking\nthey're taking calls when they aren't. If they have five minutes left, walk them through connecting one\nchannel right now instead of leaving it in the report.\n\nClose with a short plain-spoken summary and the reminder to delete or narrow that setup key.\n\n## What each thing is (for weaving into questions)\n\nOne sentence of context before the relevant question — not a feature tour up front:\n\n- **Tiers** — segment customers (Enterprise / Pro / Free) so SLAs and priority differ by who's asking.\n- **Labels** — the categories you tag tickets with (Billing, Bug, Feature Request).\n- **Tenant & thread fields** — custom data on accounts (ARR, plan) and tickets (resolution reason), for\n reporting and routing rules.\n- **Workflows** — no-code automations: when X happens, do Y (auto-label, auto-assign, auto-escalate).\n- **Help Center + Ari** — a public docs site, plus an AI that answers customers from it and any other\n knowledge sources you point at it.\n- **Sidekick** — an AI support engineer that works the queue in the background — triaging, researching,\n drafting, resolving what it can — pulling a human in only when needed, under approval rules you set.\n- **Channels** — where conversations actually arrive: email, Slack, MS Teams, chat widget, Discord.\n Connecting these needs a human OAuth click.\n\n## The interview (Mode 3, and for filling gaps in Modes 1 and 2)\n\nGrouped by topic for your reference, not for how you send them. One question per message, value narrated\nafter each answer. Skip anything already answered by an export or your research.\n\n**The basics**\n- What do you support, and what's the company called?\n- Who's on the support team? (names/emails → invites)\n\n**When a ticket comes in — what should happen?** (the important one: drives labels, workflows, escalation, SLAs)\n- What are the main things customers contact you about? (→ Label Types)\n- Do some customers get different treatment — paid vs free, or specific white-glove accounts? (→ Tiers)\n- What response times do you want to hold to, and does that vary by tier or urgency? (→ SLAs)\n- Support hours and timezone? Should SLAs pause outside them? (→ Business hours)\n- Should anything auto-route or auto-escalate? (→ Workflows, Escalation paths)\n- Any data you want tracked per ticket or per account for reporting? (→ Thread fields, Tenant fields)\n\n**Docs and knowledge**\n- Do you have customer-facing docs anywhere? URL? (→ help center migration; pull the sitemap yourself)\n- Public help center, or logged-in customers only? Should Ari answer directly from it?\n- Anything else Ari should know — status page, changelog, API docs? (→ knowledge sources)\n\n**Sidekick**\n- Should it draft replies, send them, or just assist the team? What always needs a human's OK?\n- Any internal tools it should check — Stripe, your backend, a CRM? (→ MCP servers; OAuth ones need a\n follow-up click, API-key ones you can wire now)\n- Standing instructions — tone, policies, things to never promise?\n\n**Channels and views**\n- Where do customers reach you today? (note for the report / connect at the end)\n- Any saved views the team wants on day one? (\"my open tickets,\" \"unassigned urgent\")\n\n## Building triage and routing (read the reference's §8 before you build any workflow)\n\nA few rules that matter enough to repeat here:\n\n- **Create every label with `isExcludedFromAi: true` by default.** Plain's built-in AI triage labels\n threads independently, so leaving it off means two systems fight over the same threads and the workflow\n you just built with them stops being authoritative. Only leave the AI on if they explicitly want Plain's\n own triage doing the labelling.\n- **One triage workflow, not several.** Workflow actions don't cascade into other workflows, so the\n \"triage applies a label → a routing workflow reacts to that label\" design silently never fires. Do\n classification *and* routing in one workflow on `thread.thread_created`: deterministic conditions first,\n then a single `else_if` switch of AI prompts, then chain each branch's actions\n (`apply_labels` → `set_priority` → `assign_to_user`).\n- **Audit before adding.** List existing workflows (`workflows(first: N)`) and check what's already\n published — several workflows on one trigger all fire, in no guaranteed order.\n- **Always wire the `else_if` fallback branch** to a \"Needs triage\" label so unclassified threads are\n visible rather than silently untouched.\n- **Write AI prompts in Plain's `Match if… / Don't match if…` form**, one decision each, with concrete\n examples, ordered highest-stakes first (the switch stops at the first match). Full guidance in the\n reference §8f, which mirrors Plain's own docs.\n- **Offer to hone the prompts on their real tickets.** Before writing the classification prompts, say\n something like: *\"If you can drop in an export or even a handful of recent tickets — subject lines and\n a bit of body — I'll write the AI prompts around the language your customers actually use. Otherwise\n I'll write sensible ones from what you've told me and you can tweak them in the UI later.\"* Real\n examples are the single biggest quality lever on triage accuracy: they give you the customer's own\n vocabulary, the genuine category mix, and the edge cases. If they do share tickets, group them by the\n categories they described, name the recurring phrasing in each group, and use that wording in the\n prompts. If they don't, don't push — build it and tell them where to tune it.\n- **Once the workflow is live, test it on their real examples.** Create a thread from a couple of the\n tickets they shared (or realistic ones in their domain), then read\n `stepExecutions[0].output.matchedConditionIndex` to show which branch each took. If one lands wrong,\n reword that prompt and re-run — this is the tuning loop, and doing it once in front of them teaches\n them how to maintain it.\n- **Verify the end state, not the step status** — some actions report SUCCESS while doing nothing\n (`assign_to_user` with a machine-user id is the known trap). Check the thread actually changed.\n\n## Guardrails\n\n- Don't ask for the API key until Phase 2, and never accept it as plain chat text or echo its value.\n- Never invent a mutation or field name. If it's not in the reference, or you're unsure of an argument,\n fetch the official per-operation doc — `https://www.plain.com/docs/graphql-reference/mutations/.md`\n (or `/queries/.md`), which states the arguments and the exact permission required. Full index at\n `https://www.plain.com/docs/llms.txt`; the raw schema\n (`https://core-api.uk.plain.com/graphql/v1/schema.graphql`) has the precise input-type and enum shapes.\n If you still can't confirm something exists, say so rather than guessing.\n- Always check the `error` field on a mutation's output before treating it as success.\n- Before creating things with real-world side effects (inviting teammates, publishing public help center\n articles), read back what you're about to send and get a quick confirmation. This is their production\n support workspace from day one, not a sandbox.\n- Migrating content? Actually fetch their existing pages — don't invent article text.\n- The use cases in the opening pitch aren't all equally instant, so don't promise them as if they are.\n Directly API-backed and buildable in this session: Ari answering from docs/help center, help center\n creation and migration, Linear/Jira issue creation (`createIssueTrackerIssue`, plus the Linear/Jira\n service integrations), and PostHog wiring for Sidekick (`updateSidekickPosthogConfig`). Needing a human\n OAuth click before they work: anything posting into Slack (including the weekly feature-request digest),\n and any OAuth-based MCP server such as Sentry. If they picked a Slack- or OAuth-dependent use case as\n their priority, say up front that it needs one browser click from them at the end, and make sure you\n actually walk them through that click rather than filing it in the report.\n- `Workflow.trigger` and `WorkflowRule.payload` are opaque JSON strings whose exact shape isn't documented.\n Don't guess: build one workflow in the Plain UI with them, read it back via the `workflow` query to learn\n the shape, then template from it. If that's too slow for the session, leave workflows for the report and\n say so.\n","children",[],[280],["D",1788363377561],[],[18],"926f34a3-7197-4916-a750-6b39ed4b5331","index.tsx",36,["D",1788364280307],"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\napp.get(\"/configure.md\", async (c) => {\n const md = await readFile(\"/configure.md\", import.meta.url);\n return c.text(md, 200, {\n \"content-type\": \"text/markdown; charset=utf-8\",\n \"content-disposition\": 'inline; filename=\"configure.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",[],[293],"2132424c-eda7-4678-9577-bcea615d1a9a","configure.md","1d1f56a6-a6e6-11f1-a232-1607ee4eb77e",35,["D",1788364268625],"---\nname: plain-configuration\ndescription: Applies a Plain workspace configuration over the GraphQL API. Takes an agreed config spec, validates it, creates everything in the correct dependency order, verifies each result, and reports what was built plus what still needs a human click. Called by the onboarding skill for new workspaces and by the tuning skill for changes to existing ones.\n---\n\n# Plain configuration\n\nYou apply configuration to a Plain workspace over the GraphQL API. You are the executor — something else\n(usually the onboarding skill at `https://plain-agent-setup.val.run/skill.md`, or a human directly) has\nalready decided *what* should exist. Your job is to build it correctly, verify it, and report honestly.\n\n**Read the API reference before you call anything:**\n`https://plain-agent-setup.val.run/reference.md`. Every mutation in it has been executed against a live\nworkspace, and it documents the traps that fail silently. Don't guess field names — if something isn't in\nthere, fetch the official per-operation doc at\n`https://www.plain.com/docs/graphql-reference/mutations/.md`, which also states the permission\nrequired.\n\n## Endpoint and auth\n\n`POST https://core-api.uk.plain.com/graphql/v1` with\n`Authorization: Bearer $PLAIN_SETUP_KEY` and `Content-Type: application/json`.\n\n**Never read, print, echo or log the key's value.** Reference the environment variable. If the caller\nhasn't set one, ask them to — don't accept a pasted key in the conversation. See the onboarding skill's\nkey-handling section for the exact instructions to give.\n\nBefore building anything: run `myWorkspace` and `myPermissions`. Confirm you're pointed at the workspace\nthey meant (read the name back to them — this is the last moment to catch a production workspace someone\nthought was a sandbox), and check the scopes you hold against what the config needs.\n\n---\n\n## The config spec — your input contract\n\nWhatever calls you should hand you a spec in this shape. Anything omitted simply isn't built. If you were\nhanded something looser (prose, a half-finished list), normalise it into this shape and **read it back for\nconfirmation before executing** — that read-back is the last checkpoint before real objects exist.\n\n```yaml\nworkspace: \"Acme\" # for reference only; you can't rename via this flow\n\nlabels: # → createLabelType\n - name: Billing\n icon: credit-card # slug, NOT emoji\n color: \"#22C55E\"\n externalId: billing\n excludeFromAi: true # DEFAULT TRUE — see reference §4\n\ntiers: # → createTier, then createServiceLevelAgreement per SLA\n - name: Enterprise\n externalId: enterprise\n color: \"#5B5FEF\"\n defaultThreadPriority: 1 # 0=urgent 1=high 2=normal 3=low\n isDefault: false # at most one tier true\n slas:\n - kind: first_response # first_response | next_response — SEPARATE RECORDS, never both\n minutes: 60\n priorities: [0, 1]\n businessHoursOnly: true\n warnBeforeMinutes: 15 # required; breachActions can't be empty\n\nbusinessHours: # → syncBusinessHoursSlots (replaces the whole set)\n timezone: Europe/London\n slots:\n - { weekday: MONDAY, opensAt: \"09:00\", closesAt: \"17:30\" }\n\nthreadFields: # → createThreadFieldSchema\n - label: Resolution reason\n key: resolution_reason # ^[a-z0-9_]+$, immutable\n type: ENUM # STRING | BOOL | ENUM | NUMBER | CURRENCY | DATE\n enumValues: [fixed, wontfix, duplicate, user_error]\n required: false\n aiAutoFill: true\n dependsOnLabels: [] # label names from `labels` above\n\ntenantFields: # → upsertTenantFieldSchema\n - externalFieldId: arr\n label: ARR\n type: NUMBER_TYPE # STRING_TYPE | NUMBER_TYPE | BOOLEAN_TYPE | STRING_ARRAY | DATETIME_TYPE | USER_REFERENCE_TYPE\n\nescalationPaths: # → createEscalationPath\n - name: Billing escalation\n steps:\n - { type: USER, user: \"jane@acme.com\" } # resolve to u_… ; NOT machine users\n - { type: LABEL_TYPE, label: Billing }\n\ntriage: # ONE workflow. See reference §8e before changing this shape.\n trigger: thread_created # thread_created | labels_changed | status_transitioned | schedule\n cron: null # only when trigger: schedule\n preFilters: [] # deterministic conditions first — cheap and instant\n classify: # else_if branches, evaluated IN ORDER, first match wins\n - prompt: \"Match if the customer reports a security vulnerability, exploit or data exposure — for example XSS, SQL injection or leaked credentials. Don't match for general questions about security features.\"\n then:\n label: Security\n priority: 0\n assignTo: \"security@acme.com\" # resolve to a human user id\n - prompt: \"Match if the customer reports that existing functionality is broken, erroring or timing out — for example a 500 error or a failed export. Don't match for feature requests.\"\n then:\n label: Bug\n priority: 1\n fallbackLabel: Needs triage # never leave this null\n\nsavedViews: # → createSavedThreadsView\n - name: Urgent billing\n icon: fire # slug, not emoji\n color: \"#EF4444\"\n statuses: [TODO]\n priorities: [0, 1]\n labels: [Billing]\n\nhelpCenter: # → createHelpCenter (+ groups + articles)\n publicName: Acme Help Center\n internalName: acme-help-center\n subdomain: acme # globally unique\n type: PUBLIC # PUBLIC | PRIVATE | INTERNAL\n chatEnabled: true\n ariEnabled: true\n migrateFrom: \"https://docs.acme.com/sitemap.xml\" # fetch real pages; never invent article text\n\nknowledgeSources: # → createKnowledgeSource\n - { url: \"https://acme.com/sitemap.xml\", type: SITEMAP }\n\nsidekick:\n customPrompt: \"Always mention the 30-day refund policy.\"\n customSkills:\n - { displayName: Check subscription, description: \"...\", instructions: \"...\" }\n mcpServers: [] # OAuth ones need a human click — report, don't promise\n\nwebhooks: # → createWebhookTarget\n - url: \"https://acme.com/plain-webhook\"\n events: [thread.thread_created] # webhook event names ≠ workflow event names\n\ntenants: # → upsertTenant + upsertTenantField\n - { name: Acme Inc, externalId: acme-inc, fields: { arr: 48000 }, tier: enterprise }\n\nneedsHumanClick: # things you CANNOT do — carry into the report\n invites: [{ email: jane@acme.com, role: SUPPORT }]\n channels: [email, slack]\n```\n\n---\n\n## Execution order\n\nDependencies are real — out of order means failures or orphaned config.\n\n1. **Tiers** → 2. **SLAs** (need `tierId`) → 3. **Business hours** → 4. **Labels** → 5. **Tenant field\nschemas** → 6. **Thread field schemas** (may reference labels) → 7. **Escalation paths** (reference\nlabels + users) → 8. **Triage workflow** (needs label, user and tier IDs to exist) → 9. **Saved views** →\n10. **Help center** → groups → articles → 11. **Knowledge sources** → 12. **Sidekick** → 13. **Webhooks**\n→ 14. **Tenants + field values**.\n\nKeep a running map of `name → real ID` as you go. Everything downstream references IDs, and workflow step\npayloads embed them — a name-based payload silently applies nothing.\n\n## How to execute\n\n- **Resolve identities first.** Fetch `users(first: N) { edges { node { id publicName } } }` and map any\n emails in the spec to real `u_…` IDs. `assign_to_user` with a machine user id returns SUCCESS and\n assigns nobody — see reference. If an email doesn't match a workspace member, don't guess: move that\n assignment into `needsHumanClick` and say so.\n- **One thing at a time, narrated.** Say what you're creating, create it, confirm with the real ID. Group\n only trivially-related items (a batch of labels). Never fire ten mutations and report once.\n- **Check `error` on every mutation** before treating it as success — `error { message code fields { field message } }`. The\n `fields` array names exactly what's wrong and is usually enough to fix and retry immediately.\n- **On failure:** say what failed, in plain language, with the real message. Then either fix and retry\n (validation errors usually tell you the fix), skip it and record it for the report, or ask — but never\n silently swallow it and never loop.\n- **Verify end state, not step status.** Some operations report success while doing nothing. After the\n triage workflow is published, create one test thread and read\n `workflowExecutions → stepExecutions[].output.matchedConditionIndex` to prove the branch fired and the\n label, priority and assignment actually landed on the thread.\n\n## Building the triage workflow\n\nThe single most error-prone part. Full detail in reference §8, but the shape:\n\n1. `createWorkflow` with the JSON trigger — this creates an **inactive draft**.\n2. Create the **terminal action steps first** (leaf-first), because `transitions` needs real step IDs.\n Chain each branch's actions: `apply_labels` → `set_priority` → `assign_to_user`.\n3. Create the **`else_if` classify step** with one prompt per branch and\n `transitions: [branch1, branch2, …, fallback]` — N conditions, N+1 transitions.\n4. Any deterministic pre-filters go *above* the classify step, pointing at it on the true branch.\n5. `updateWorkflow { startStepId, isPublished: true }` — until you do this it never runs.\n\n**Before creating a new workflow, audit what's already published:**\n`workflows(first: 20) { edges { node { id name publishedAt { iso8601 } } } }`. Multiple published\nworkflows on one trigger all fire with no ordering guarantee — the classic symptom is every thread getting\nan unexpected label. If a conflicting one exists, tell the caller and agree whether to unpublish it rather\nthan stacking another on top.\n\nTo modify an existing published workflow: unpublish (`isPublished: false`), restructure, republish.\n`startStepId` can't be cleared while published.\n\n## What you cannot do — always report these\n\n- **Invite teammates.** `inviteUserToWorkspace` refuses machine users outright. Collect them into the\n report as a UI task (Settings → Members). `assignRolesToUser` on an existing user does work.\n- **Complete channel OAuth** (Slack, MS Teams, Discord, email forwarding) or OAuth MCP servers. You can\n provision shells; consent needs a browser. **Support is not live until a channel is connected** — say\n so plainly rather than letting someone believe they're taking tickets.\n- **Set personal notification preferences.** No mutation exists; per-user, avatar → Preferences.\n- **Place the chat widget snippet** on their own site.\n- **Disable Plain's built-in AI triage**, which labels *and* sets priority independently of your workflow.\n Mitigate by creating labels with `excludeFromAi: true`; for priority, flag Settings → Agents.\n\n## Output\n\nReturn two things to whatever called you:\n\n1. **Built** — every object created, with its real ID, grouped by area. Machine-readable enough that a\n caller can render it (the onboarding skill turns this into an HTML report).\n2. **Needs a human** — invites, channel OAuth, notification preferences, widget snippet, plus anything\n that failed and why. Name the exact Settings page for each.\n\nThen remind them to delete the setup machine user or narrow its key — it can create tiers, invite-adjacent\nconfig and publish public help center content.\n",[],[301],"67a4f1c1-3637-4404-9e16-6d13683b3dae","README.md","01a061e4-3acb-7070-a926-8c4f90b26c5e",["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",[],[185,316],"dfa17abd-085c-45c1-81d7-cd10c11b9b60","favicon.svg","01a061e4-3acb-7070-a926-842f4e54d674",["D",1788348742264],"\n",[],[185,326],"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",[],[185,333],"3a3e2c48-1639-4f15-8dbd-d059b930e785",["D",1788348742264],"directory",[271,272,273],[185],["D",1788348742264],{"_11":12,"_229":82},{"_11":12,"_225":-5,"_81":82,"_30":80,"_226":227,"_228":24},{"_51":216,"_13":16,"_45":48,"_217":180,"_218":-5,"_219":-5,"_220":-5,"_221":-5,"_222":-5,"_223":14,"_224":12},"ctx",{"_66":-5,"_248":382,"_383":384,"_385":386,"_387":24,"_388":24,"_389":24,"_390":193,"_391":-5,"_392":-7,"_393":-7,"_394":26,"_395":24,"_396":24,"_397":-5,"_398":24,"_399":24,"_400":24,"_401":-5},"ENV",{"_353":354,"_355":356,"_357":16,"_358":359,"_360":361,"_362":363,"_364":365,"_366":367,"_368":369,"_370":371,"_372":373,"_374":375,"_376":377,"_378":379,"_380":381},"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"]

History · reference.md