picked 0.0.101 → 0.0.102-next.2

package/docs/reference/management-api/schema/project.md

@@ -6,13 +6,14 @@ generated: true
 
 # Project schema
 
-The operations and types that `project.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
 
 ## Queries
 
 ### `project`
 
-Fetch a single project by ID. Requires authentication.
+Reads a project. Null when no project has the ID.
+Scope: `ORGANIZATION_PROJECTS_READ`.
 
 ```graphql
 project(input: ProjectInput!): Project @auth
@@ -20,9 +21,8 @@ project(input: ProjectInput!): Project @auth
 
 ### `projects`
 
-List projects the authenticated user can reach, across every organisation they
-belong to. Pass `organizationId` to narrow the list to one organisation, and
-`search` to match project names case-insensitively. Requires authentication.
+Lists the projects the user can reach, across every organisation they belong to. `search`
+matches a case-insensitive substring of the name. Empty for an API key.
 
 ```graphql
 projects(organizationId: ID, first: Int, after: String, search: String, sortKey: ProjectSortKeys = NAME, reverse: Boolean = false): ProjectConnection! @auth
@@ -32,7 +32,8 @@ projects(organizationId: ID, first: Int, after: String, search: String, sortKey:
 
 ### `projectCreate`
 
-Create a new project. Requires scope: `ORGANIZATION_PROJECTS_CREATE`.
+Creates a project, with a draft workspace named `Default`.
+Scope: `ORGANIZATION_PROJECTS_CREATE`.
 
 ```graphql
 projectCreate(input: ProjectCreateInput!): ProjectCreatePayload! @auth
@@ -40,7 +41,8 @@ projectCreate(input: ProjectCreateInput!): ProjectCreatePayload! @auth
 
 ### `projectUpdate`
 
-Update a project. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Updates a project's name or brief.
+Scope: `ORGANIZATION_PROJECTS_UPDATE`.
 
 ```graphql
 projectUpdate(input: ProjectUpdateInput!): ProjectUpdatePayload! @auth
@@ -48,7 +50,8 @@ projectUpdate(input: ProjectUpdateInput!): ProjectUpdatePayload! @auth
 
 ### `projectDelete`
 
-Delete a project. Requires scope: `ORGANIZATION_PROJECTS_DELETE`.
+Deletes a project.
+Scope: `ORGANIZATION_PROJECTS_DELETE`.
 
 ```graphql
 projectDelete(input: ProjectDeleteInput!): ProjectDeletePayload! @auth
@@ -56,7 +59,8 @@ projectDelete(input: ProjectDeleteInput!): ProjectDeletePayload! @auth
 
 ### `projectPreviewEnvironmentCreate`
 
-Create a project preview environment. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Creates a preview environment on a project. Invalid input comes back as `userErrors`.
+Scope: `ORGANIZATION_PROJECTS_UPDATE`.
 
 ```graphql
 projectPreviewEnvironmentCreate(input: ProjectPreviewEnvironmentCreateInput!): ProjectPreviewEnvironmentCreatePayload! @auth
@@ -64,7 +68,8 @@ projectPreviewEnvironmentCreate(input: ProjectPreviewEnvironmentCreateInput!): P
 
 ### `projectPreviewEnvironmentUpdate`
 
-Update a project preview environment. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Updates a preview environment. Invalid input comes back as `userErrors`.
+Scope: `ORGANIZATION_PROJECTS_UPDATE`.
 
 ```graphql
 projectPreviewEnvironmentUpdate(input: ProjectPreviewEnvironmentUpdateInput!): ProjectPreviewEnvironmentUpdatePayload! @auth
@@ -72,7 +77,8 @@ projectPreviewEnvironmentUpdate(input: ProjectPreviewEnvironmentUpdateInput!): P
 
 ### `projectPreviewEnvironmentDelete`
 
-Delete a project preview environment. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Deletes a preview environment. An unknown ID comes back as `userErrors`.
+Scope: `ORGANIZATION_PROJECTS_UPDATE`.
 
 ```graphql
 projectPreviewEnvironmentDelete(input: ProjectPreviewEnvironmentDeleteInput!): ProjectPreviewEnvironmentDeletePayload! @auth
@@ -83,18 +89,13 @@ projectPreviewEnvironmentDelete(input: ProjectPreviewEnvironmentDeleteInput!): P
 ### `ProjectSortKeys`
 
 ```graphql
-"""
-Sort keys accepted by `Organization.projects(...)`. Pair with `reverse: true`
-to flip the order.
-"""
+"""The orders a project list can take. `reverse: true` flips the order."""
 enum ProjectSortKeys {
-  """Sort by project `name` (alphabetical)."""
+  """By name, A to Z."""
   NAME
-  """Sort by `createdAt`."""
+  """By creation time, oldest first."""
   CREATED_AT
-  """
-  Sort by `updatedAt`. Pair with `reverse: true` for most-recently-changed first.
-  """
+  """By last change, oldest first."""
   UPDATED_AT
 }
 ```
@@ -102,20 +103,13 @@ enum ProjectSortKeys {
 ### `WorkspaceSortKeys`
 
 ```graphql
-"""
-Sort keys accepted by `Project.workspaces(...)`. Pair with `reverse: true`
-to flip the order.
-
-`DRAFT_CHANGED_AT` orders by the last draft content change, which is what
-"most recently worked on" means for a workspace; `Workspace` carries no
-`updatedAt`.
-"""
+"""The orders a workspace list can take. `reverse: true` flips the order."""
 enum WorkspaceSortKeys {
-  """Sort by workspace `name` (alphabetical)."""
+  """By name, A to Z."""
   NAME
-  """Sort by `createdAt`."""
+  """By creation time, oldest first."""
   CREATED_AT
-  """Sort by `draftChangedAt`."""
+  """By the last change to the draft, oldest first."""
   DRAFT_CHANGED_AT
 }
 ```
@@ -124,101 +118,98 @@ enum WorkspaceSortKeys {
 
 ```graphql
 """
-A project — an isolated A/B testing surface under an organisation.
-
-Projects own workspaces (DRAFT / LIVE / ARCHIVED), CMS content, reports,
-and integrations. `LIVE` is derived, not stored. At most one workspace is
-live at a time (the one owning the project's served version), and
-`liveWorkspaceVersion` exposes that currently-published immutable snapshot
-(null until the first publish).
-
-The `timezone` field anchors analytics aggregations (e.g. "yesterday")
-and is immutable after creation.
+One site or one application. Each project has its own experiences, content and configuration,
+and belongs to one organisation.
 """
 type Project {
-  """Unique project identifier."""
+  """The ID of the project."""
   id: ID!
-  """Display name of the project."""
+  """The name of the project."""
   name: String!
-  """ID of the organisation this project belongs to."""
+  """The ID of the organisation the project belongs to."""
   organizationId: ID!
-  """When this project was created."""
+  """When the project was created."""
   createdAt: DateTime!
-  """When this project was last updated."""
+  """When the project last changed."""
   updatedAt: DateTime!
   """
-  IANA timezone identifier used for analytics aggregations (e.g. `America/New_York`). Immutable after creation.
+  The IANA time zone that analytics days follow, such as `America/New_York`. Set on create and
+  fixed after.
   """
   timezone: String
   """
-  Author-provided markdown brief (audience, tone, goals, value props, entry points). Read by the Picked AI agents. Null until set.
+  The project brief in Markdown: audience, tone, goals, value propositions, entry points. Picked's
+  AI agents read it. Null until set.
   """
   context: String
-  """The organisation this project belongs to."""
+  """The organisation the project belongs to."""
   organization: Organization!
-  """Configuration settings for this project (key/value pairs)."""
+  """
+  The settings of the project, as key/value pairs.
+  Scope: `ORGANIZATION_PROJECTS_READ`.
+  """
   settings: [ProjectSetting!]!
   """
-  SDK presence recorded against this project, or null when none was ever recorded.
+  The SDK presence recorded for the project. Null when none was recorded.
+  Scope: `ORGANIZATION_PROJECTS_READ`.
   """
   sdkPresence: SdkPresence @deprecated(reason: "No SDK version records presence. Reads frozen rows; will be removed.")
   """
-  The workspace that owns the project's currently-served version, or null if
-  the project has never been published. Requires authentication.
+  The workspace whose version the project serves. Null until the first publish.
   """
   liveWorkspace: Workspace @auth
   """
-  The version this project currently serves (resolved through
-  `projects.live_workspace_version_id`), or null if no workspace has been
-  published yet. After a rollback this may be an earlier version, not the
-  most recently published one. The snapshot's `config_json` blob is
-  intentionally not exposed. Use `workspaceDiff` to read its contents.
-  Requires authentication.
+  The version the project serves. Null until the first publish. After a restore it can be an
+  earlier version than the latest. Read its contents with `workspaceDiff`.
+  Scope: `ORGANIZATION_WORKSPACE_READ`.
   """
   liveWorkspaceVersion: WorkspaceVersion @auth
   """
-  Every published version across all of the project's workspaces, ordered
-  newest-first by `publishedAt`. This is the project-wide rollback history:
-  each version carries the `workspace` it was published from, and the one
-  matching `liveWorkspaceVersion` is the currently-served version. Versions
-  owned by a soft-deleted workspace are excluded. Supports forward
-  (`first`/`after`) and backward (`last`/`before`) pagination with stable
-  cursors over `(publishedAt, id)`. Requires authentication.
+  Every published version across the project's workspaces, newest first: the history a restore
+  picks from. Versions of a deleted workspace are left out.
+  Scope: `ORGANIZATION_WORKSPACE_READ`.
   """
   workspaceVersions(first: Int, after: String, last: Int, before: String): WorkspaceVersionConnection! @auth
   """
-  Workspaces belonging to this project. Filter by name with `search`
-  (case-insensitive substring) and by status with `status`, which keeps
-  workspaces holding any of the listed statuses and applies to `totalCount`
-  too. `HIDDEN` matches nothing, since snapshots never appear here. Requires
-  authentication.
+  The workspaces of the project. `search` matches a case-insensitive substring of the name;
+  `status` keeps workspaces holding any listed status, and `totalCount` follows it. `HIDDEN`
+  matches nothing.
   """
   workspaces(first: Int, after: String, last: Int, before: String, search: String, status: [WorkspaceStatus!], sortKey: WorkspaceSortKeys = CREATED_AT, reverse: Boolean = false): WorkspaceConnection! @auth
-  """Reports associated with this project. Requires authentication."""
+  """
+  The reports on the project.
+  Scope: `ORGANIZATION_REPORTS_READ`.
+  """
   reports(first: Int, after: String, sortKey: ReportSortKeys = NAME, reverse: Boolean = false): ProjectReportConnection! @auth
-  """All integrations installed for this project. Requires authentication."""
+  """
+  The integrations installed on the project.
+  Scope: `ORGANIZATION_INTEGRATIONS_READ`.
+  """
   integrations: [Integration!]! @auth
   """
-  A specific integration by type, or null if not installed. Requires authentication.
+  The integration of a type. Null when it is not installed.
+  Scope: `ORGANIZATION_INTEGRATIONS_READ`.
   """
   integration(type: IntegrationType!): Integration @auth
   """
-  Third-party MCP servers registered to this project. Requires authentication.
+  The third-party MCP servers registered to the project.
+  Scope: `ORGANIZATION_INTEGRATIONS_READ`.
   """
   mcpServers(first: Int, after: String): McpServerConnection! @auth
   """
-  External APIs registered to this project — the origins its workflows may call. Requires authentication.
+  The external APIs registered to the project: the origins its workflows may call.
+  Scope: `ORGANIZATION_INTEGRATIONS_READ`.
   """
   externalApis(first: Int, after: String): ExternalApiConnection! @auth
   """
-  The project's own labels, ordered by namespace then key: state a workflow or a
-  person keeps for the whole project, such as a counter or a lock. An expired
-  label is not listed. Project labels outlive every lead. Write them with `labelsSet`, `ownerType: PROJECT` and the
-  project's id. Requires scope: `ORGANIZATION_PROJECTS_READ`.
+  The project's own labels, such as a counter or a lock, ordered by namespace then key. Expired
+  labels are left out. Write them with `labelsSet` and `ownerType: PROJECT`.
+  Scope: `ORGANIZATION_PROJECTS_READ`.
   """
   labels: [Label!]! @auth
   """
-  Leads captured by this project, newest first by default. Requires scope: `ORGANIZATION_LEADS_READ`.
+  The leads the project captured, newest first by default.
+  Scope: `ORGANIZATION_LEADS_READ`.
   """
   leads(
     first: Int
@@ -234,62 +225,54 @@ type Project {
     """
     query: String
     """
-    The path to order by, in the same grammar `query` uses:
-    `labels.<namespace>.<key>`, `responses.<key>`, or `id`, `userId`,
-    `createdAt`. A path naming nothing sortable orders by capture time, so a
-    hand-edited URL degrades rather than fails. Leads carrying no value at the
-    path sort last in either direction. A query with a `session.` clause lists
-    its leads by their capture events, newest first unless `reverse` is false,
-    and takes either no sort or `createdAt`; any other sort is a validation error.
+    The path to order by, in the grammar `query` uses: `labels.<namespace>.<key>`,
+    `responses.<key>`, `id`, `userId` or `createdAt`. A path naming nothing sortable orders by
+    capture time. Leads with no value at the path sort last in either direction. A query with a
+    `session.` clause orders by capture event and takes no sort or `createdAt` alone.
     """
     sort: String
     reverse: Boolean = true
     """
-    Narrows the leads to those captured inside this window, in the project's
-    time zone. `totalCount` and `metrics` count under the same window, and a
-    metric measures over it unless given its own.
+    The window, in the project's time zone, the leads were captured inside. `totalCount` and
+    `metrics` count under it, and a metric measures over it unless given its own.
     """
     window: MetricWindowInput
     """
-    How the leads captured under one SDK session id read. `SESSION` lists each
-    session's newest matching lead alone, and `matchCount` and `metrics` count
-    sessions. A query with a `session.` clause takes `NONE` alone.
+    How leads captured in one SDK session read. `SESSION` lists each session's newest matching
+    lead alone, and `matchCount` and `metrics` count sessions. A query with a `session.` clause
+    takes `NONE` alone.
     """
     collapse: LeadCollapse = NONE
   ): LeadConnection! @auth
   """
-  The Leads reports on this project, in order: how leads are
-  acquired, the journeys behind them, and how visits convert to leads. Each is
-  a signed guest embed URL with the project locked and the date range left
-  editable, read from the project's analytics warehouse. Requires scope:
-  `ORGANIZATION_LEADS_READ` or `ORGANIZATION_REPORTS_READ`.
+  The Leads reports on the project, in order: how leads are acquired, the journeys behind them,
+  and how visits convert to leads. Each is a signed embed URL locked to the project, with an
+  editable date range.
+  Scope: `ORGANIZATION_LEADS_READ` or `ORGANIZATION_REPORTS_READ`.
   """
   leadReports: [LeadReport!]! @auth
   """
-  The Sessions reports on this project, in order: how its sessions arrive, the
-  journeys they take, and which of them convert. Each is a signed guest embed URL
-  with the project locked and the date range left editable, read from the
-  project's analytics warehouse. Requires scope: `ORGANIZATION_LEADS_READ`.
+  The Sessions reports on the project, in order: how its sessions arrive, the journeys they take,
+  and which of them convert. Each is a signed embed URL locked to the project, with an editable
+  date range.
+  Scope: `ORGANIZATION_LEADS_READ` or `ORGANIZATION_REPORTS_READ`.
   """
   analyticsSessionsReports: [AnalyticsSessionsReport!]! @auth
   """
-  One visitor session on this project's sites, read from the project's analytics
-  warehouse across all of its events, anchored on its latest lead capture, else on
-  its latest timeline event. Null when the warehouse holds no event of it. Requires
-  scope: `ORGANIZATION_LEADS_READ`.
+  One visitor session on the project's sites, across all of its events, anchored on its latest
+  lead capture, else on its latest timeline event. Null when no event of it is recorded.
+  Scope: `ORGANIZATION_LEADS_READ`.
   """
   analyticsSession(
-    """The identity resolver's session identifier."""
+    """The ID of the session."""
     id: ID!
   ): AnalyticsSession @auth
   """
-  Visitor sessions on this project's sites, newest first by when they started, read
-  from the project's analytics warehouse. A session is its events inside `window`,
-  so one that began before the window starts at its first event inside it, and its
-  `summary` adds up those events alone. Pages by keyset: `first` and `after` read
-  older sessions, `last` and `before` newer ones; a page holds at most 100. The
-  newest events can take a few minutes to arrive. Requires scope:
-  `ORGANIZATION_LEADS_READ`.
+  The visitor sessions on the project's sites, newest first by start. A session is its events
+  inside `window`, and its `summary` adds up those events alone. `first` and `after` read older
+  sessions, `last` and `before` newer ones, at most 100 a page. The newest events can take a few
+  minutes to arrive.
+  Scope: `ORGANIZATION_LEADS_READ`.
   """
   analyticsSessions(
     first: Int
@@ -297,8 +280,8 @@ type Project {
     last: Int
     before: String
     """
-    The window the sessions' events fall inside, in the project's time zone.
-    Defaults to today and the six days before it.
+    The window, in the project's time zone, the sessions' events fall inside. Defaults to today
+    and the six days before it.
     """
     window: MetricWindowInput
     """
@@ -324,20 +307,18 @@ type Project {
     includeBots: Boolean = false
   ): AnalyticsSessionConnection! @auth
   """
-  Saved views of one of this project's lists, oldest first. Requires scope:
-  `ORGANIZATION_PROJECTS_READ`.
+  The saved views of one of the project's lists, oldest first.
+  Scope: `ORGANIZATION_PROJECTS_READ`.
   """
   savedViews(
-    """Which list to read the views of."""
+    """The list to read the views of."""
     resource: SavedViewResource!
     first: Int
     after: String
     last: Int
     before: String
   ): SavedViewConnection! @auth
-  """
-  Customer-site URLs registered for embedding CMS page previews, ordered by `createdAt` ascending.
-  """
+  """The preview environments of the project, oldest first."""
   previewEnvironments: [ProjectPreviewEnvironment!]!
 }
 ```
@@ -346,14 +327,16 @@ type Project {
 
 ```graphql
 """
-A customer-installed SDK URL (Production, Staging, etc.) used by the page-preview iframe.
+A named site with the SDK installed, such as Production or Staging, that a preview opens on.
 """
 type ProjectPreviewEnvironment {
+  """The ID of the preview environment."""
   id: ID!
-  """Human-readable label (e.g. 'Production', 'Staging'). 1-40 characters."""
+  """The name of the preview environment, 1 to 40 characters."""
   label: String!
   """
-  Origin or URL where the SDK is installed; the dashboard appends `?picked-preview-token=<token>`.
+  The origin or URL of the site. A preview opens it with a `picked-preview-token` query
+  parameter.
   """
   url: String!
 }
@@ -362,15 +345,19 @@ type ProjectPreviewEnvironment {
 ### `ProjectPreviewEnvironmentErrorCode`
 
 ```graphql
-"""
-Validation error code returned by the projectPreviewEnvironment* mutations.
-"""
+"""The validation errors of the preview environment operations."""
 enum ProjectPreviewEnvironmentErrorCode {
+  """No project has the ID."""
   PROJECT_NOT_FOUND
+  """No preview environment has the ID."""
   ENVIRONMENT_NOT_FOUND
+  """The label is empty."""
   LABEL_REQUIRED
+  """The label is longer than 40 characters."""
   LABEL_TOO_LONG
+  """The URL is empty."""
   URL_REQUIRED
+  """The URL does not parse."""
   URL_INVALID
 }
 ```
@@ -378,15 +365,13 @@ enum ProjectPreviewEnvironmentErrorCode {
 ### `ProjectPreviewEnvironmentUserError`
 
 ```graphql
-"""
-User-facing validation error returned by the projectPreviewEnvironment* mutations.
-"""
+"""A validation error from a preview environment operation."""
 type ProjectPreviewEnvironmentUserError {
-  """Path to the offending input field, e.g. ['label']."""
+  """The path to the input field at fault, such as `["label"]`."""
   field: [String!]
-  """Human-readable message suitable for display."""
+  """A message to show the user."""
   message: String!
-  """Machine-readable error code."""
+  """The error code."""
   code: ProjectPreviewEnvironmentErrorCode!
 }
 ```
@@ -394,10 +379,15 @@ type ProjectPreviewEnvironmentUserError {
 ### `ProjectPreviewEnvironmentCreateInput`
 
 ```graphql
-"""Input for creating a project preview environment."""
+"""The input of `projectPreviewEnvironmentCreate`."""
 input ProjectPreviewEnvironmentCreateInput {
+  """The ID of the project."""
   projectId: ID!
+  """The name of the preview environment, 1 to 40 characters."""
   label: String!
+  """
+  The origin or URL of the site. Without a protocol, `https://` is assumed.
+  """
   url: String!
 }
 ```
@@ -405,11 +395,13 @@ input ProjectPreviewEnvironmentCreateInput {
 ### `ProjectPreviewEnvironmentCreatePayload`
 
 ```graphql
-"""Payload returned by `projectPreviewEnvironmentCreate`."""
+"""The result of `projectPreviewEnvironmentCreate`."""
 type ProjectPreviewEnvironmentCreatePayload {
-  """The created environment, or null when input failed validation."""
+  """
+  The created preview environment. Null when the input failed validation.
+  """
   environment: ProjectPreviewEnvironment
-  """Per-field validation errors; empty on success."""
+  """The validation errors. Empty on success."""
   userErrors: [ProjectPreviewEnvironmentUserError!]!
 }
 ```
@@ -417,10 +409,15 @@ type ProjectPreviewEnvironmentCreatePayload {
 ### `ProjectPreviewEnvironmentUpdateInput`
 
 ```graphql
-"""Input for updating a project preview environment."""
+"""
+The input of `projectPreviewEnvironmentUpdate`. Every field is required.
+"""
 input ProjectPreviewEnvironmentUpdateInput {
+  """The ID of the preview environment."""
   id: ID!
+  """The name of the preview environment, 1 to 40 characters. Required."""
   label: String!
+  """The origin or URL of the site. Required."""
   url: String!
 }
 ```
@@ -428,11 +425,13 @@ input ProjectPreviewEnvironmentUpdateInput {
 ### `ProjectPreviewEnvironmentUpdatePayload`
 
 ```graphql
-"""Payload returned by `projectPreviewEnvironmentUpdate`."""
+"""The result of `projectPreviewEnvironmentUpdate`."""
 type ProjectPreviewEnvironmentUpdatePayload {
-  """The updated environment, or null when input failed validation."""
+  """
+  The updated preview environment. Null when the input failed validation.
+  """
   environment: ProjectPreviewEnvironment
-  """Per-field validation errors; empty on success."""
+  """The validation errors. Empty on success."""
   userErrors: [ProjectPreviewEnvironmentUserError!]!
 }
 ```
@@ -440,8 +439,9 @@ type ProjectPreviewEnvironmentUpdatePayload {
 ### `ProjectPreviewEnvironmentDeleteInput`
 
 ```graphql
-"""Input for deleting a project preview environment."""
+"""The input of `projectPreviewEnvironmentDelete`."""
 input ProjectPreviewEnvironmentDeleteInput {
+  """The ID of the preview environment."""
   id: ID!
 }
 ```
@@ -449,13 +449,13 @@ input ProjectPreviewEnvironmentDeleteInput {
 ### `ProjectPreviewEnvironmentDeletePayload`
 
 ```graphql
-"""Payload returned by `projectPreviewEnvironmentDelete`."""
+"""The result of `projectPreviewEnvironmentDelete`."""
 type ProjectPreviewEnvironmentDeletePayload {
   """
-  ID of the deleted environment, or null when the input failed validation.
+  The ID of the deleted preview environment. Null when the input failed validation.
   """
   deletedEnvironmentId: ID
-  """Per-field validation errors; empty on success."""
+  """The validation errors. Empty on success."""
   userErrors: [ProjectPreviewEnvironmentUserError!]!
 }
 ```
@@ -463,15 +463,11 @@ type ProjectPreviewEnvironmentDeletePayload {
 ### `ProjectSetting`
 
 ```graphql
-"""
-A single key/value setting on a project. The shape of `value` depends on
-`key`; well-known keys are documented in the dashboard. Free-form keys
-are allowed for use by integrations and the SDK plugin system.
-"""
+"""One setting of a project. The shape of `value` depends on `key`."""
 type ProjectSetting {
-  """Setting key. Stable across SDK versions."""
+  """The key of the setting."""
   key: String!
-  """Setting value as a JSON value. Shape depends on the key."""
+  """The value of the setting."""
   value: JSON!
 }
 ```
@@ -480,14 +476,13 @@ type ProjectSetting {
 
 ```graphql
 """
-SDK presence recorded against a project. The rows are frozen: `lastSeenAt`
-reports the last boot recorded while presence tracking was live, so it answers
-"when did this project last report in", not "is the SDK reaching us now".
+The SDK presence recorded for a project. The records are frozen: `lastSeenAt` is the last boot
+recorded while tracking ran, not whether the SDK is reaching Picked today.
 """
 type SdkPresence {
-  """ID of the project this presence belongs to."""
+  """The ID of the project."""
   projectId: ID!
-  """When the SDK was last seen booting."""
+  """When the SDK was last seen booting. Null when unknown."""
   lastSeenAt: DateTime
   """Always null."""
   sdkVersion: String
@@ -499,9 +494,9 @@ type SdkPresence {
 ### `ProjectEdge`
 
 ```graphql
-"""Edge type for `ProjectConnection`."""
+"""A project in a page of results."""
 type ProjectEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The project."""
   node: Project!
@@ -511,13 +506,13 @@ type ProjectEdge {
 ### `ProjectConnection`
 
 ```graphql
-"""Relay-style connection of projects."""
+"""A page of projects."""
 type ProjectConnection {
-  """List of project edges."""
+  """The edges in this page."""
   edges: [ProjectEdge!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of projects."""
+  """The total number of projects."""
   totalCount: Int!
 }
 ```
@@ -525,9 +520,9 @@ type ProjectConnection {
 ### `ProjectInput`
 
 ```graphql
-"""Input for looking up a single project."""
+"""The input of `project`."""
 input ProjectInput {
-  """Project ID to look up."""
+  """The ID of the project."""
   id: ID!
 }
 ```
@@ -535,14 +530,14 @@ input ProjectInput {
 ### `ProjectCreateInput`
 
 ```graphql
-"""Input for `projectCreate`."""
+"""The input of `projectCreate`."""
 input ProjectCreateInput {
-  """Name of the project."""
+  """The name of the project. Must not be blank."""
   name: String!
-  """ID of the organisation to create the project in."""
+  """The ID of the organisation to create the project in."""
   organizationId: ID!
   """
-  IANA timezone identifier for analytics and reporting (e.g. `America/New_York`). Cannot be changed after creation.
+  The IANA time zone that analytics days follow, such as `America/New_York`. Fixed after.
   """
   timezone: String!
 }
@@ -551,9 +546,9 @@ input ProjectCreateInput {
 ### `ProjectCreatePayload`
 
 ```graphql
-"""Payload returned by `projectCreate`."""
+"""The result of `projectCreate`."""
 type ProjectCreatePayload {
-  """The newly created project."""
+  """The created project."""
   project: Project
 }
 ```
@@ -561,17 +556,13 @@ type ProjectCreatePayload {
 ### `ProjectUpdateInput`
 
 ```graphql
-"""
-Input for `projectUpdate`. Only mutable fields are accepted — `timezone` is immutable.
-"""
+"""The input of `projectUpdate`. Omit a field to keep its value."""
 input ProjectUpdateInput {
-  """ID of the project to update."""
+  """The ID of the project."""
   id: ID!
-  """New name for the project. Omit to leave unchanged."""
+  """The name of the project. Must not be blank."""
   name: String
-  """
-  New markdown context brief. Omit to leave unchanged; pass an empty string to clear.
-  """
+  """The project brief in Markdown. An empty string clears it."""
   context: String
 }
 ```
@@ -579,7 +570,7 @@ input ProjectUpdateInput {
 ### `ProjectUpdatePayload`
 
 ```graphql
-"""Payload returned by `projectUpdate`."""
+"""The result of `projectUpdate`."""
 type ProjectUpdatePayload {
   """The updated project."""
   project: Project
@@ -589,9 +580,9 @@ type ProjectUpdatePayload {
 ### `ProjectDeleteInput`
 
 ```graphql
-"""Input for `projectDelete`."""
+"""The input of `projectDelete`."""
 input ProjectDeleteInput {
-  """ID of the project to delete."""
+  """The ID of the project."""
   id: ID!
 }
 ```
@@ -599,9 +590,9 @@ input ProjectDeleteInput {
 ### `ProjectDeletePayload`
 
 ```graphql
-"""Payload returned by `projectDelete`."""
+"""The result of `projectDelete`."""
 type ProjectDeletePayload {
-  """ID of the deleted project."""
+  """The ID of the deleted project."""
   deletedProjectId: ID
 }
 ```