picked 0.0.101 → 0.0.102-next.2

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

@@ -6,13 +6,14 @@ generated: true
 
 # Step schema
 
-The operations and types that `step.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
 
 ### `step`
 
-Get a step by ID within a workspace.
+Reads a step.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 step(id: ID!, workspaceId: ID!): Step @auth
@@ -20,7 +21,9 @@ step(id: ID!, workspaceId: ID!): Step @auth
 
 ### `steps`
 
-Get list of steps within a workspace.
+Lists the steps in a workspace. `search` matches a case-insensitive substring of the name;
+`sortKey` and `reverse` set the order.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 steps(first: Int, after: String, last: Int, before: String, workspaceId: ID!, search: String, sortKey: StepSortKeys = NAME, reverse: Boolean = false): StepConnection! @auth
@@ -30,7 +33,8 @@ steps(first: Int, after: String, last: Int, before: String, workspaceId: ID!, se
 
 ### `stepCreate`
 
-Create a new step. Requires scope: `ORGANIZATION_PROJECTS_CREATE`.
+Creates a step in a workspace.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 stepCreate(input: StepCreateInput!): StepCreatePayload! @auth
@@ -38,7 +42,8 @@ stepCreate(input: StepCreateInput!): StepCreatePayload! @auth
 
 ### `stepUpdate`
 
-Update a step. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Updates a step.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 stepUpdate(input: StepUpdateInput!): StepUpdatePayload! @auth
@@ -46,7 +51,9 @@ stepUpdate(input: StepUpdateInput!): StepUpdatePayload! @auth
 
 ### `stepDelete`
 
-Delete a step. Requires scope: `ORGANIZATION_PROJECTS_DELETE`.
+Deletes a step. A step that an experience references is not deleted, and comes back as an
+`IN_USE` user error.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 stepDelete(input: StepDeleteInput!): StepDeletePayload! @auth
@@ -58,42 +65,34 @@ stepDelete(input: StepDeleteInput!): StepDeletePayload! @auth
 
 ```graphql
 """
-A step within a workspace. Rendered by the SDK as one screen of UI when
-the flow reaches a `StepNode` referencing this step.
-
-Carries a list of `Field`s (form inputs) and an optional `layoutName` or
-`layoutContentEntry` (the layout the SDK renders the fields into). The
-fields are workspace-level resources shared across steps; `Step.fields`
-returns this step's selection.
+One screen that a visitor sees. It holds fields, and a flow shows it when it reaches a step node.
 """
 type Step {
-  """Unique step identifier."""
+  """The ID of the step."""
   id: ID!
-  """Display name of the step."""
+  """The name of the step."""
   name: String!
-  """Stable, human-readable key for SDK consumers."""
+  """The stable identifier of the step, unique within its workspace."""
   key: String!
-  """Optional description of the step."""
+  """A description of the step. Null when none is set."""
   description: String
   """
-  Name of the layout the SDK should render this step with (free-form string, plug-in defined).
+  The layout name: the component that renders the step, such as `card` or `modal`. Null when none is set.
   """
   layoutName: String
   """
-  Optional 1:1 reference to the CMS Content Entry that backs this step's layout. Mutually exclusive with `layoutName`.
+  The content entry that holds the step's layout content. Null when none is attached.
   """
   layoutContentEntry: ContentEntry
-  """When this step was created."""
+  """When the step was created."""
   createdAt: DateTime!
-  """When this step was last updated."""
+  """When the step last changed."""
   updatedAt: DateTime!
-  """The workspace this step belongs to."""
+  """The workspace the step belongs to."""
   workspace: Workspace!
-  """
-  The workspace ID this step belongs to (denormalised for query convenience).
-  """
+  """The ID of the workspace the step belongs to."""
   workspaceId: ID
-  """Fields within this step."""
+  """The fields on the step, in order."""
   fields(first: Int, after: String, last: Int, before: String): FieldConnection!
 }
 ```
@@ -101,9 +100,9 @@ type Step {
 ### `StepEdge`
 
 ```graphql
-"""Edge type for `StepConnection`."""
+"""A step in a page of results."""
 type StepEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The step."""
   node: Step!
@@ -113,19 +112,15 @@ type StepEdge {
 ### `StepConnection`
 
 ```graphql
-"""
-Relay-style connection of steps, with both an `edges` list and a flat `nodes` accessor.
-"""
+"""A page of steps."""
 type StepConnection {
-  """List of step edges."""
+  """The edges in this page."""
   edges: [StepEdge!]!
-  """
-  Flat list of steps, equivalent to `edges[].node`. Convenience accessor.
-  """
+  """The steps in this page."""
   nodes: [Step!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of steps."""
+  """The number of steps across all pages, ignoring `search`."""
   totalCount: Int!
 }
 ```
@@ -133,21 +128,23 @@ type StepConnection {
 ### `StepCreateInput`
 
 ```graphql
-"""Input for `stepCreate`."""
+"""The input of `stepCreate`."""
 input StepCreateInput {
-  """Workspace ID to create the step in."""
+  """The ID of the workspace to create the step in."""
   workspaceId: ID!
-  """Display name for the step."""
+  """The name of the step."""
   name: String!
-  """Unique key identifier for the step."""
+  """
+  The stable identifier of the step, unique within the workspace. It cannot change later.
+  """
   key: String!
-  """Optional description."""
+  """A description of the step."""
   description: String
-  """Name of the layout the SDK should render this step with."""
-  layoutName: String
   """
-  IDs of workspace-level fields to associate with this step. Order is preserved.
+  The layout name: the component that renders the step, such as `card` or `modal`.
   """
+  layoutName: String
+  """The IDs of the fields to put on the step, in order."""
   fieldIds: [ID!]
 }
 ```
@@ -155,7 +152,7 @@ input StepCreateInput {
 ### `StepCreatePayload`
 
 ```graphql
-"""Payload returned by `stepCreate`."""
+"""The result of `stepCreate`."""
 type StepCreatePayload {
   """The created step."""
   step: Step
@@ -165,24 +162,25 @@ type StepCreatePayload {
 ### `StepUpdateInput`
 
 ```graphql
-"""Input for `stepUpdate`. Omit a field to leave it unchanged."""
+"""The input of `stepUpdate`. Omit a field to keep its value."""
 input StepUpdateInput {
-  """Step ID."""
+  """The ID of the step."""
   id: ID!
-  """Workspace ID the step belongs to."""
+  """The ID of the workspace the step belongs to."""
   workspaceId: ID!
-  """New display name."""
+  """The name of the step."""
   name: String
-  """New description."""
+  """A description of the step. Null clears it."""
   description: String
-  """New layout name."""
+  """The layout name: the component that renders the step. Null clears it."""
   layoutName: String
   """
-  ID of the CMS Content Entry to use as this step's layout. Pass null to detach the entry; mutually exclusive with `layoutName`.
+  The ID of a content entry to attach as the step's layout. The entry must be in the step's
+  workspace and belong to a page-layout or step-layout model. Null detaches the current entry.
   """
   layoutContentEntryId: ID
   """
-  IDs of workspace-level fields to associate with this step. Replaces the existing field list when set.
+  The IDs of the fields on the step, in order. Replaces the current list.
   """
   fieldIds: [ID!]
 }
@@ -191,7 +189,7 @@ input StepUpdateInput {
 ### `StepUpdatePayload`
 
 ```graphql
-"""Payload returned by `stepUpdate`."""
+"""The result of `stepUpdate`."""
 type StepUpdatePayload {
   """The updated step."""
   step: Step
@@ -201,11 +199,11 @@ type StepUpdatePayload {
 ### `StepDeleteInput`
 
 ```graphql
-"""Input for `stepDelete`."""
+"""The input of `stepDelete`."""
 input StepDeleteInput {
-  """Step ID."""
+  """The ID of the step."""
   id: ID!
-  """Workspace ID the step belongs to."""
+  """The ID of the workspace the step belongs to."""
   workspaceId: ID!
 }
 ```
@@ -213,13 +211,11 @@ input StepDeleteInput {
 ### `StepDeletePayload`
 
 ```graphql
-"""
-Payload returned by `stepDelete`. Returns `userErrors` when the step is in use.
-"""
+"""The result of `stepDelete`."""
 type StepDeletePayload {
-  """ID of the deleted step (null when `userErrors` is non-empty)."""
+  """The ID of the deleted step. Null when `userErrors` is not empty."""
   deletedStepId: ID
-  """Validation errors. Empty array indicates success."""
+  """The reasons the step was not deleted. Empty on success."""
   userErrors: [StepDeleteUserError!]!
 }
 ```
@@ -227,11 +223,9 @@ type StepDeletePayload {
 ### `StepDeleteUserErrorCode`
 
 ```graphql
-"""Machine-readable error codes for `stepDelete`."""
+"""The reasons `stepDelete` refuses a delete."""
 enum StepDeleteUserErrorCode {
-  """
-  The step is referenced by one or more experiences and cannot be deleted.
-  """
+  """An experience references the step."""
   IN_USE
 }
 ```
@@ -239,18 +233,18 @@ enum StepDeleteUserErrorCode {
 ### `StepDeleteUserError`
 
 ```graphql
-"""
-A user error from `stepDelete`. Carries the experiences that block the delete when `code` is `IN_USE`.
-"""
+"""A reason `stepDelete` did not delete a step."""
 type StepDeleteUserError {
-  """Path to the input field that caused the error."""
+  """
+  The path to the input field at fault. Null when no single field is at fault.
+  """
   field: [String!]
-  """Human-readable error message."""
+  """A message to show the user."""
   message: String!
-  """Machine-readable error code."""
+  """A machine-readable code."""
   code: StepDeleteUserErrorCode!
   """
-  Experiences that reference this step (present when `code` is `IN_USE`).
+  The experiences that reference the step. Null unless `code` is `IN_USE`.
   """
   referencingExperiences: [ReferencingExperience!]
 }
@@ -259,15 +253,13 @@ type StepDeleteUserError {
 ### `StepSortKeys`
 
 ```graphql
-"""
-Sort keys for `steps(...)`. Pair with `reverse: true` to flip the order (`NAME` + `reverse: false` sorts A→Z; `CREATED_AT` + `reverse: true` is newest-first).
-"""
+"""The orders `steps` can sort by. `reverse: true` flips each."""
 enum StepSortKeys {
-  """Sort by `name` (alphabetical)."""
+  """By name, A to Z."""
   NAME
-  """Sort by `createdAt`."""
+  """By creation time, oldest first."""
   CREATED_AT
-  """Sort by `updatedAt`."""
+  """By last change, oldest first."""
   UPDATED_AT
 }
 ```

package/docs/reference/management-api/schema/tenant-branding.md

@@ -6,13 +6,14 @@ generated: true
 
 # Tenant branding schema
 
-The operations and types that `tenant-branding.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
 
 ### `tenant`
 
-Resolve a tenant (and its branding) by host or explicit slug. Unauthenticated; cached for 5 minutes.
+Reads a tenant and its branding by slug or hostname. Returns the default tenant when neither
+matches. Needs no authentication, and responses are cacheable for 5 minutes.
 
 ```graphql
 tenant(input: TenantInput!): Tenant! @cache(policy: "public, max-age=300, stale-while-revalidate=3600")
@@ -23,15 +24,15 @@ tenant(input: TenantInput!): Tenant! @cache(policy: "public, max-age=300, stale-
 ### `Tenant`
 
 ```graphql
-"""A tenant dashboard deployment (e.g. `picked`, `convincely`)."""
+"""
+A deployment of the dashboard with its own hostnames and branding, such as `picked`.
+"""
 type Tenant {
-  """
-  Machine-readable identifier for the tenant (e.g. `picked`, `convincely`).
-  """
+  """The tenant's identifier, such as `picked`."""
   slug: String!
-  """Hostnames this tenant serves the dashboard on."""
+  """The hostnames the tenant serves the dashboard on."""
   hosts: [String!]!
-  """Visual identity for this tenant — logos, colours, radii."""
+  """The tenant's logos, colours and border radii."""
   branding: Branding!
 }
 ```
@@ -39,17 +40,15 @@ type Tenant {
 ### `Branding`
 
 ```graphql
-"""
-Visual identity for a tenant — logos, colour palette, and shape tokens.
-"""
+"""The visual identity of a tenant."""
 type Branding {
-  """Human-readable product name shown in chrome and document titles."""
+  """The product name shown in the dashboard and in page titles."""
   productName: String!
-  """Logos used throughout the dashboard."""
+  """The tenant's logos."""
   logos: BrandingLogos!
-  """Brand colour tokens."""
+  """The tenant's colours."""
   colors: BrandingColors!
-  """Border-radius tokens."""
+  """The tenant's border radii."""
   radii: BrandingRadii!
 }
 ```
@@ -57,15 +56,13 @@ type Branding {
 ### `BrandingLogos`
 
 ```graphql
-"""
-Logo URLs for a tenant. Paths are absolute relative to the dashboard origin.
-"""
+"""The logos of a tenant, as paths from the dashboard origin."""
 type BrandingLogos {
-  """Small logo shown in the dashboard header."""
+  """The small logo in the dashboard header."""
   header: String!
-  """Larger logo shown on authentication pages (sign-in, OAuth)."""
+  """The larger logo on the sign-in and authorisation pages."""
   auth: String!
-  """Optional favicon URL."""
+  """The favicon. Null when the tenant has none."""
   favicon: String
 }
 ```
@@ -73,17 +70,15 @@ type BrandingLogos {
 ### `BrandingColors`
 
 ```graphql
-"""
-Brand colour tokens for a tenant. Values are CSS colour expressions (`#rrggbb`, `rgb(...)`, etc.).
-"""
+"""The colours of a tenant, as CSS colour values such as `#rrggbb`."""
 type BrandingColors {
-  """Primary brand colour."""
+  """The primary brand colour."""
   primary: String!
-  """Focus / outline ring colour used across the site."""
+  """The colour of focus rings."""
   focusRing: String!
-  """Colour tokens for unauthenticated / auth pages."""
+  """The colours of the sign-in pages."""
   auth: BrandingAuthColors!
-  """Colour tokens for authenticated / app pages."""
+  """The colours of the signed-in dashboard."""
   app: BrandingAppColors!
 }
 ```
@@ -91,19 +86,17 @@ type BrandingColors {
 ### `BrandingAuthColors`
 
 ```graphql
-"""
-Colour tokens used on authentication pages (sign-in, OAuth callback, etc.).
-"""
+"""The colours of a tenant's sign-in and authorisation pages."""
 type BrandingAuthColors {
-  """Full auth page background."""
+  """The page background."""
   shellBg: String!
-  """`AuthModal` / sign-in card background."""
+  """The sign-in card background."""
   cardBg: String!
-  """Primary text colour on auth pages."""
+  """The text colour."""
   text: String!
-  """Primary button background on auth pages."""
+  """The primary button background."""
   buttonBg: String!
-  """Primary button text colour on auth pages."""
+  """The primary button text colour."""
   buttonText: String!
 }
 ```
@@ -111,37 +104,31 @@ type BrandingAuthColors {
 ### `BrandingAppColors`
 
 ```graphql
-"""Colour tokens used on authenticated application pages."""
+"""The colours of a tenant's signed-in dashboard."""
 type BrandingAppColors {
-  """Authenticated app shell (header / sidebar chrome) background."""
+  """The background of the header and sidebar frame."""
   shellBg: String!
-  """
-  Foreground colour for chrome (text + icons) sitting on the shell background.
-  """
+  """The colour of text and icons on the frame background."""
   shellText: String!
-  """Primary content area background (what sits inside the shell)."""
+  """The content area background."""
   contentBg: String!
   """
-  Subdued content background (used for card subdued variants and similar muted surfaces inside the content area).
+  The background of muted surfaces in the content area, such as subdued cards.
   """
   contentBgSubdued: String!
-  """
-  Page-level background sitting behind page content (the main scroll viewport).
-  """
+  """The background behind page content."""
   pageBg: String!
-  """Subtle surface background for card headers and similar chrome."""
+  """The background of card headers and similar surfaces."""
   surfaceBg: String!
-  """Sidebar (left nav rail) background."""
+  """The sidebar background."""
   sidebarBg: String!
-  """
-  Neutral surface background used for secondary buttons and similar muted chrome.
-  """
+  """The background of secondary buttons and similar neutral surfaces."""
   neutralBg: String!
-  """Primary text colour in the content area."""
+  """The text colour in the content area."""
   text: String!
-  """Primary button background in the app."""
+  """The primary button background."""
   buttonBg: String!
-  """Primary button text colour in the app."""
+  """The primary button text colour."""
   buttonText: String!
 }
 ```
@@ -149,13 +136,11 @@ type BrandingAppColors {
 ### `BrandingRadii`
 
 ```graphql
-"""
-Border-radius tokens for a tenant. Values are CSS length expressions (`8px`, `0.5rem`, etc.).
-"""
+"""The border radii of a tenant, as CSS lengths such as `8px`."""
 type BrandingRadii {
-  """Border radius for buttons."""
+  """The border radius of buttons."""
   button: String!
-  """Border radius for cards."""
+  """The border radius of cards."""
   card: String!
 }
 ```
@@ -163,22 +148,15 @@ type BrandingRadii {
 ### `TenantInput`
 
 ```graphql
-"""
-Input for the `tenant` query. Either `host`, `slug`, both, or neither
-may be provided.
-
-When both are absent the default tenant is returned. When `slug` is set
-it wins over `host`. When only `host` is set, the server resolves the
-slug from the host registry; unknown hosts fall back to the default
-tenant.
-"""
+"""The input of `tenant`. Both fields are optional."""
 input TenantInput {
   """
-  Dashboard hostname (e.g. `dashboard.convincely.com`). Used when `slug` is absent or unknown.
+  The dashboard hostname, such as `dashboard.convincely.com`. Used when `slug` is null or matches
+  no tenant.
   """
   host: String
   """
-  Explicit tenant slug override. Wins over `host` when it matches a registered tenant.
+  The tenant's slug. Takes precedence over `host` when it matches a tenant.
   """
   slug: String
 }