[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_228":229,"_230":231},"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",19,"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","reference.md","latestPath","fileId","4f726ce8-a6c2-11f1-9a6d-1607ee4eb77e","name","fileType","content","# 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`EscalationPathStepType` has exactly two values — **`USER`** (provide `userId`; human or machine user) and\n**`LABEL_TYPE`** (provide `labelTypeId`; targets that label type's owners). There is no `ASSIGN_USER` or\n`ADD_LABEL`.\n\n```graphql\nmutation {\n createEscalationPath(input: {\n name: \"Billing escalation\"\n description: \"Escalate unresolved billing issues after 24h\"\n steps: [\n { type: USER, userId: \"...\" }\n { type: LABEL_TYPE, labelTypeId: \"...\" }\n ]\n }) { escalationPath { id } error { message code } }\n}\n```\n\n## 8. Workflows (no-code automations)\n\n**A workflow is three things, not one.** `createWorkflow` alone gives you an inactive draft that does\nnothing. To get a working automation you need: the workflow (trigger) → its steps → a `startStepId` → then\npublish it. Miss any of those and it silently never runs.\n\n### 8a. Create the workflow with its trigger\n\n`trigger` is a JSON-encoded string, shaped `{ \"type\": , ... }`. The three valid types:\n\n| type | extra fields | behaviour |\n|---|---|---|\n| `manual` | none | runs only via `triggerWorkflow` or a UI button |\n| `events` | `events: string[]` (≥1) | runs on domain events |\n| `schedule` | `cron: string` | recurring, evaluated in UTC |\n\nKnown event strings: `thread.thread_created`, `thread.message_added`, `thread.thread_field_updated`,\n`thread.thread_labels_changed`, `thread.thread_status_transitioned`.\n\n```graphql\nmutation {\n createWorkflow(input: {\n name: \"Route billing tickets\"\n trigger: \"{\\\"type\\\":\\\"events\\\",\\\"events\\\":[\\\"thread.thread_created\\\"]}\"\n }) { workflow { id } error { message code } }\n}\n```\nThe `schedule` type is what makes recurring digests possible — e.g. a weekly feature-request summary is\n`{\"type\":\"schedule\",\"cron\":\"0 9 * * MON\"}` plus a `send_slack_notification` action step.\n\n### 8b. Add steps\n\n```graphql\nmutation {\n createWorkflowStep(input: {\n workflowId: \"...\"\n type: ACTION # CONDITION | ACTION | WAIT\n name: \"Label as billing\"\n payload: \"{\\\"version\\\":1,\\\"type\\\":\\\"apply_labels\\\",\\\"labelTypeIds\\\":[\\\"lt_...\\\"]}\"\n transitions: [null] # ACTION: 1 element. CONDITION: 2 (true, false). null = terminal\n positionX: 0\n positionY: 0\n }) { workflowStep { id } error { message code } }\n}\n```\nEvery payload is an object with `version: 1` and a `type` discriminator:\n- **CONDITION** — a leaf check (`contains_label`, `thread_field_equals`, `thread_field_is_set`,\n `priority_equals`, `assigned_to`, `customer_equals`, `ai_workflow_rule_condition`) or a combinator\n (`and`, `or`, `not`, `else_if`) nesting others under `conditions`/`condition`.\n- **ACTION** — `apply_labels`, `remove_labels`, `set_priority`, `set_status`, `set_tier`,\n `assign_to_user`, `assign_to_team`, `add_note`, `send_message`, `send_slack_notification`,\n `send_http_request`, `set_thread_field`, `snooze_thread`, `escalate_thread`.\n- **WAIT** — `{ \"duration\": , \"cancelCondition\"?: }`.\n\n`bulkUpsertWorkflowSteps` sets the whole step list at once (missing IDs get deleted) and can set\n`startStepId` and `trigger` in the same call — usually the better tool when building from scratch.\n\n**Payloads embed workspace-specific IDs** (label type IDs, user IDs, tier IDs). They are not portable:\ncopying a payload into another workspace references IDs that don't exist there and the step silently\napplies nothing. Always resolve real IDs in *this* workspace first.\n\n### 8c. Wire up and publish\n\n```graphql\nmutation {\n updateWorkflow(input: {\n workflowId: \"...\"\n startStepId: { value: \"...\" }\n isPublished: { value: true }\n }) { workflow { id publishedAt } error { message code } }\n}\n```\n`publishedAt: null` means it's still an inactive draft. Note: `startStepId` can't be cleared on a\npublished workflow — unpublish (`isPublished: { value: false }`), restructure, then republish.\n\nAlso available: `workflowTemplateGallery` / `workflowTemplate` queries and `exportWorkflowTemplate` —\nworth checking for a prebuilt template before hand-rolling. `createWorkflowRule` (with its own JSON\n`payload`) is a separate, older rules system; prefer workflows unless you have a reason not to.\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","createdAt",["D",1788360592445],"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":224,"_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":225,"_80":226,"_82":227,"_84":25},"tree",[176,180,181,182,183],"files",[176,177,178,179,180,181,182,183],"counts",{"_166":62,"_167":157,"_168":62,"_169":170,"_171":172},"contents",[126,127,128,129,130],"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},{"_42":161,"_32":49,"_30":162,"_134":-5,"_40":41,"_39":157,"_136":58,"_37":163,"_13":62,"_33":164,"_34":-5,"_24":25,"_140":-5,"_27":165},{"_42":154,"_32":155,"_30":156,"_134":-5,"_40":41,"_39":157,"_136":58,"_37":158,"_13":62,"_33":20,"_34":159,"_24":25,"_140":-5,"_27":160},{"_42":146,"_32":147,"_30":56,"_134":-5,"_40":41,"_39":148,"_136":25,"_37":149,"_13":150,"_33":151,"_34":152,"_24":25,"_140":44,"_27":153},{"_42":142,"_32":28,"_30":31,"_134":-5,"_40":41,"_39":14,"_136":25,"_37":143,"_13":144,"_33":20,"_34":36,"_24":25,"_140":-5,"_27":145},{"_42":131,"_32":132,"_30":133,"_134":-5,"_40":41,"_39":135,"_136":25,"_37":137,"_13":138,"_33":20,"_34":139,"_24":25,"_140":-5,"_27":141},"98244f62-b304-48a0-ac22-a19442dc4d20","skill.md","2b885d4c-a6c2-11f1-a2fb-1607ee4eb77e","parentId",16,"latest",["D",1788359153908],6,"---\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\nFor the complete GraphQL reference — exact mutation names and input fields, cleansed from Plain's live\nschema — read `https://plain-agent-setup.val.run/reference.md` now. Don't guess field names; that\nreference (or the live schema at the URL inside it) is the source of truth. Read it silently — don't\nnarrate that you're reading it, don't summarize it, don't dump it back 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.** Save the agreed config to a local file (e.g.\n`plain-workspace-config.md`) before you send them off to make an API key. Creating a machine user takes a\nfew minutes of tab-switching, and if this session drops, that file is what saves them from redoing the\nwhole interview. It's also something they can show their team for sign-off before anything real is created.\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 build it.** Confirm the key works silently, tell them in one line that you're connected, and start\nexecuting in the dependency order from the reference (tiers → SLAs → business hours → labels → fields →\nescalation paths → workflows → views → help center → knowledge sources → Sidekick → webhooks → invites →\ntenants). For each thing: say what you're making, make it, confirm with the real ID. Now the value language\nswitches to past tense, because it genuinely exists — and they can see it in that Plain tab. Keep a running\nsense of progress (\"that's tiers and SLAs done, help center next\"). If a mutation errors, say so plainly\nwith the real message, and tell them what you're doing about it — retrying with a fix, skipping it for the\nreport, or needing a decision from them. Never silently swallow it or loop.\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: connecting\n Slack / MS Teams / Discord / email channels, embedding the chat widget on their site, completing OAuth\n for any MCP servers, and each teammate's personal notification preferences. Name the exact Settings page\n 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## 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, check the live schema\n (`https://core-api.uk.plain.com/graphql/v1/schema.graphql`) or say you couldn't confirm it exists.\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","label",[132],"0789fe37-9807-4e5d-9e08-7f3d309e1e68",["D",1788360592445],3,[28],"2793764e-f599-4dde-8a08-5ded28a5ede0","index.tsx",7,["D",1788352189431],2,"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",[147],"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,198],"dfa17abd-085c-45c1-81d7-cd10c11b9b60","favicon.svg","01a061e4-3acb-7070-a926-842f4e54d674",["D",1788348742264],"\n",[],[49,207],"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,214],["D",1788348742264],[177,178,179],[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":261,"_262":263,"_264":265,"_266":25,"_267":25,"_268":25,"_269":58,"_270":-5,"_271":-7,"_272":-7,"_273":62,"_274":25,"_275":25,"_276":-5,"_277":25,"_278":25,"_279":25,"_280":-5},"ENV",{"_232":233,"_234":235,"_236":86,"_237":238,"_239":240,"_241":242,"_243":244,"_245":246,"_247":248,"_249":250,"_251":252,"_253":254,"_255":256,"_257":258,"_259":260},"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 · v19