picked 0.0.101-next.2 → 0.0.101

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

@@ -0,0 +1,273 @@
+---
+type: reference
+layout: docs
+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.
+
+## Queries
+
+### `step`
+
+Get a step by ID within a workspace.
+
+```graphql
+step(id: ID!, workspaceId: ID!): Step @auth
+```
+
+### `steps`
+
+Get list of steps within a workspace.
+
+```graphql
+steps(first: Int, after: String, last: Int, before: String, workspaceId: ID!, search: String, sortKey: StepSortKeys = NAME, reverse: Boolean = false): StepConnection! @auth
+```
+
+## Mutations
+
+### `stepCreate`
+
+Create a new step. Requires scope: `ORGANIZATION_PROJECTS_CREATE`.
+
+```graphql
+stepCreate(input: StepCreateInput!): StepCreatePayload! @auth
+```
+
+### `stepUpdate`
+
+Update a step. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+stepUpdate(input: StepUpdateInput!): StepUpdatePayload! @auth
+```
+
+### `stepDelete`
+
+Delete a step. Requires scope: `ORGANIZATION_PROJECTS_DELETE`.
+
+```graphql
+stepDelete(input: StepDeleteInput!): StepDeletePayload! @auth
+```
+
+## Types
+
+### `Step`
+
+```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.
+"""
+type Step {
+  """Unique step identifier."""
+  id: ID!
+  """Display name of the step."""
+  name: String!
+  """Stable, human-readable key for SDK consumers."""
+  key: String!
+  """Optional description of the step."""
+  description: String
+  """
+  Name of the layout the SDK should render this step with (free-form string, plug-in defined).
+  """
+  layoutName: String
+  """
+  Optional 1:1 reference to the CMS Content Entry that backs this step's layout. Mutually exclusive with `layoutName`.
+  """
+  layoutContentEntry: ContentEntry
+  """When this step was created."""
+  createdAt: DateTime!
+  """When this step was last updated."""
+  updatedAt: DateTime!
+  """The workspace this step belongs to."""
+  workspace: Workspace!
+  """
+  The workspace ID this step belongs to (denormalised for query convenience).
+  """
+  workspaceId: ID
+  """Fields within this step."""
+  fields(first: Int, after: String, last: Int, before: String): FieldConnection!
+}
+```
+
+### `StepEdge`
+
+```graphql
+"""Edge type for `StepConnection`."""
+type StepEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The step."""
+  node: Step!
+}
+```
+
+### `StepConnection`
+
+```graphql
+"""
+Relay-style connection of steps, with both an `edges` list and a flat `nodes` accessor.
+"""
+type StepConnection {
+  """List of step edges."""
+  edges: [StepEdge!]!
+  """
+  Flat list of steps, equivalent to `edges[].node`. Convenience accessor.
+  """
+  nodes: [Step!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of steps."""
+  totalCount: Int!
+}
+```
+
+### `StepCreateInput`
+
+```graphql
+"""Input for `stepCreate`."""
+input StepCreateInput {
+  """Workspace ID to create the step in."""
+  workspaceId: ID!
+  """Display name for the step."""
+  name: String!
+  """Unique key identifier for the step."""
+  key: String!
+  """Optional description."""
+  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.
+  """
+  fieldIds: [ID!]
+}
+```
+
+### `StepCreatePayload`
+
+```graphql
+"""Payload returned by `stepCreate`."""
+type StepCreatePayload {
+  """The created step."""
+  step: Step
+}
+```
+
+### `StepUpdateInput`
+
+```graphql
+"""Input for `stepUpdate`. Omit a field to leave it unchanged."""
+input StepUpdateInput {
+  """Step ID."""
+  id: ID!
+  """Workspace ID the step belongs to."""
+  workspaceId: ID!
+  """New display name."""
+  name: String
+  """New description."""
+  description: String
+  """New layout name."""
+  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`.
+  """
+  layoutContentEntryId: ID
+  """
+  IDs of workspace-level fields to associate with this step. Replaces the existing field list when set.
+  """
+  fieldIds: [ID!]
+}
+```
+
+### `StepUpdatePayload`
+
+```graphql
+"""Payload returned by `stepUpdate`."""
+type StepUpdatePayload {
+  """The updated step."""
+  step: Step
+}
+```
+
+### `StepDeleteInput`
+
+```graphql
+"""Input for `stepDelete`."""
+input StepDeleteInput {
+  """Step ID."""
+  id: ID!
+  """Workspace ID the step belongs to."""
+  workspaceId: ID!
+}
+```
+
+### `StepDeletePayload`
+
+```graphql
+"""
+Payload returned by `stepDelete`. Returns `userErrors` when the step is in use.
+"""
+type StepDeletePayload {
+  """ID of the deleted step (null when `userErrors` is non-empty)."""
+  deletedStepId: ID
+  """Validation errors. Empty array indicates success."""
+  userErrors: [StepDeleteUserError!]!
+}
+```
+
+### `StepDeleteUserErrorCode`
+
+```graphql
+"""Machine-readable error codes for `stepDelete`."""
+enum StepDeleteUserErrorCode {
+  """
+  The step is referenced by one or more experiences and cannot be deleted.
+  """
+  IN_USE
+}
+```
+
+### `StepDeleteUserError`
+
+```graphql
+"""
+A user error from `stepDelete`. Carries the experiences that block the delete when `code` is `IN_USE`.
+"""
+type StepDeleteUserError {
+  """Path to the input field that caused the error."""
+  field: [String!]
+  """Human-readable error message."""
+  message: String!
+  """Machine-readable error code."""
+  code: StepDeleteUserErrorCode!
+  """
+  Experiences that reference this step (present when `code` is `IN_USE`).
+  """
+  referencingExperiences: [ReferencingExperience!]
+}
+```
+
+### `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).
+"""
+enum StepSortKeys {
+  """Sort by `name` (alphabetical)."""
+  NAME
+  """Sort by `createdAt`."""
+  CREATED_AT
+  """Sort by `updatedAt`."""
+  UPDATED_AT
+}
+```

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

@@ -0,0 +1,185 @@
+---
+type: reference
+layout: docs
+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.
+
+## Queries
+
+### `tenant`
+
+Resolve a tenant (and its branding) by host or explicit slug. Unauthenticated; cached for 5 minutes.
+
+```graphql
+tenant(input: TenantInput!): Tenant! @cache(policy: "public, max-age=300, stale-while-revalidate=3600")
+```
+
+## Types
+
+### `Tenant`
+
+```graphql
+"""A tenant dashboard deployment (e.g. `picked`, `convincely`)."""
+type Tenant {
+  """
+  Machine-readable identifier for the tenant (e.g. `picked`, `convincely`).
+  """
+  slug: String!
+  """Hostnames this tenant serves the dashboard on."""
+  hosts: [String!]!
+  """Visual identity for this tenant — logos, colours, radii."""
+  branding: Branding!
+}
+```
+
+### `Branding`
+
+```graphql
+"""
+Visual identity for a tenant — logos, colour palette, and shape tokens.
+"""
+type Branding {
+  """Human-readable product name shown in chrome and document titles."""
+  productName: String!
+  """Logos used throughout the dashboard."""
+  logos: BrandingLogos!
+  """Brand colour tokens."""
+  colors: BrandingColors!
+  """Border-radius tokens."""
+  radii: BrandingRadii!
+}
+```
+
+### `BrandingLogos`
+
+```graphql
+"""
+Logo URLs for a tenant. Paths are absolute relative to the dashboard origin.
+"""
+type BrandingLogos {
+  """Small logo shown in the dashboard header."""
+  header: String!
+  """Larger logo shown on authentication pages (sign-in, OAuth)."""
+  auth: String!
+  """Optional favicon URL."""
+  favicon: String
+}
+```
+
+### `BrandingColors`
+
+```graphql
+"""
+Brand colour tokens for a tenant. Values are CSS colour expressions (`#rrggbb`, `rgb(...)`, etc.).
+"""
+type BrandingColors {
+  """Primary brand colour."""
+  primary: String!
+  """Focus / outline ring colour used across the site."""
+  focusRing: String!
+  """Colour tokens for unauthenticated / auth pages."""
+  auth: BrandingAuthColors!
+  """Colour tokens for authenticated / app pages."""
+  app: BrandingAppColors!
+}
+```
+
+### `BrandingAuthColors`
+
+```graphql
+"""
+Colour tokens used on authentication pages (sign-in, OAuth callback, etc.).
+"""
+type BrandingAuthColors {
+  """Full auth page background."""
+  shellBg: String!
+  """`AuthModal` / sign-in card background."""
+  cardBg: String!
+  """Primary text colour on auth pages."""
+  text: String!
+  """Primary button background on auth pages."""
+  buttonBg: String!
+  """Primary button text colour on auth pages."""
+  buttonText: String!
+}
+```
+
+### `BrandingAppColors`
+
+```graphql
+"""Colour tokens used on authenticated application pages."""
+type BrandingAppColors {
+  """Authenticated app shell (header / sidebar chrome) background."""
+  shellBg: String!
+  """
+  Foreground colour for chrome (text + icons) sitting on the shell background.
+  """
+  shellText: String!
+  """Primary content area background (what sits inside the shell)."""
+  contentBg: String!
+  """
+  Subdued content background (used for card subdued variants and similar muted surfaces inside the content area).
+  """
+  contentBgSubdued: String!
+  """
+  Page-level background sitting behind page content (the main scroll viewport).
+  """
+  pageBg: String!
+  """Subtle surface background for card headers and similar chrome."""
+  surfaceBg: String!
+  """Sidebar (left nav rail) background."""
+  sidebarBg: String!
+  """
+  Neutral surface background used for secondary buttons and similar muted chrome.
+  """
+  neutralBg: String!
+  """Primary text colour in the content area."""
+  text: String!
+  """Primary button background in the app."""
+  buttonBg: String!
+  """Primary button text colour in the app."""
+  buttonText: String!
+}
+```
+
+### `BrandingRadii`
+
+```graphql
+"""
+Border-radius tokens for a tenant. Values are CSS length expressions (`8px`, `0.5rem`, etc.).
+"""
+type BrandingRadii {
+  """Border radius for buttons."""
+  button: String!
+  """Border radius for cards."""
+  card: String!
+}
+```
+
+### `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.
+"""
+input TenantInput {
+  """
+  Dashboard hostname (e.g. `dashboard.convincely.com`). Used when `slug` is absent or unknown.
+  """
+  host: String
+  """
+  Explicit tenant slug override. Wins over `host` when it matches a registered tenant.
+  """
+  slug: String
+}
+```

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

@@ -0,0 +1,246 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Workbench schema
+
+The operations and types that `workbench.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Mutations
+
+### `workbenchAssetImport`
+
+Imports an Asset owned elsewhere into a Workbench, creating an `IMPORTED` membership. Removing the import (`workbenchAssetRemove`) drops only the join, never the Asset.
+
+```graphql
+workbenchAssetImport(input: WorkbenchAssetImportInput!): WorkbenchAssetImportPayload! @auth
+```
+
+### `workbenchAssetAdoptOwned`
+
+Adopts an existing project-library Asset as `OWNED` by a Workbench, transferring the Asset's ownership. Used when a Create-Page upload is bound to its Workbench after the Workbench is created.
+
+```graphql
+workbenchAssetAdoptOwned(input: WorkbenchAssetAdoptOwnedInput!): WorkbenchAssetAdoptOwnedPayload! @auth
+```
+
+### `workbenchAssetRemove`
+
+Removes an Asset's membership from a Workbench. If the membership was `OWNED`, the Asset is also soft-deleted; if `IMPORTED`, only the join is dropped.
+
+```graphql
+workbenchAssetRemove(input: WorkbenchAssetRemoveInput!): WorkbenchAssetRemovePayload! @auth
+```
+
+## Types
+
+### `WorkbenchAssetRelationship`
+
+```graphql
+"""How an Asset relates to the Workbench it is joined to."""
+enum WorkbenchAssetRelationship {
+  """
+  Authored or uploaded directly into this Workbench. Soft-deleted when removed.
+  """
+  OWNED
+  """
+  A reference to an Asset owned elsewhere (for example a Design System's DESIGN.md). Removing it drops only the join.
+  """
+  IMPORTED
+}
+```
+
+### `WorkbenchOwner`
+
+```graphql
+"""Identifies the logical entity a Workbench belongs to."""
+type WorkbenchOwner {
+  """The owner kind: `"experience"` or `"design_system"`."""
+  type: String!
+  """
+  The owner's stable cross-workspace reference: an Experience's `key`, or a Design System's `id`.
+  """
+  ref: String!
+}
+```
+
+### `WorkbenchAsset`
+
+```graphql
+"""One Asset's membership in a Workbench."""
+type WorkbenchAsset {
+  """
+  Whether this Asset is owned by the Workbench or imported from elsewhere.
+  """
+  relationship: WorkbenchAssetRelationship!
+  """
+  The logical path of this Asset within the Workbench, if one was assigned at upload time.
+  """
+  path: String
+  """The Asset."""
+  asset: Asset!
+  """
+  The Design System this Asset was imported from, when it is a Design System's file; null otherwise.
+  """
+  sourceDesignSystem: DesignSystem
+}
+```
+
+### `WorkbenchAssetEdge`
+
+```graphql
+"""Edge type for `WorkbenchAssetConnection`."""
+type WorkbenchAssetEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The Workbench-Asset membership."""
+  node: WorkbenchAsset!
+}
+```
+
+### `WorkbenchAssetConnection`
+
+```graphql
+"""
+Relay-style connection of Workbench-Asset memberships, with both an `edges` list and a flat `nodes` accessor.
+"""
+type WorkbenchAssetConnection {
+  """List of Workbench-Asset membership edges."""
+  edges: [WorkbenchAssetEdge!]!
+  """
+  Flat list of Workbench-Asset memberships, equivalent to `edges[].node`.
+  """
+  nodes: [WorkbenchAsset!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """
+  Total number of memberships in this Workbench, optionally filtered by `relationship`.
+  """
+  totalCount: Int!
+}
+```
+
+### `Workbench`
+
+```graphql
+"""
+A cross-workspace working directory for a logical entity (an Experience or a
+Design System), associated by `(project, ownerType, ownerRef)`. A Workbench is
+NOT scoped to a workspace version, so one Workbench serves every workspace of
+a project that shares the owner reference — including duplicates, since
+workspace duplication preserves an Experience's `key`.
+"""
+type Workbench {
+  """Unique Workbench identifier."""
+  id: ID!
+  """The logical entity this Workbench belongs to."""
+  owner: WorkbenchOwner!
+  """
+  The Assets joined to this Workbench, each carrying its `relationship` and logical `path`.
+  """
+  assets(
+    """
+    Filter to only `OWNED` or only `IMPORTED` memberships. Omit to return both.
+    """
+    relationship: WorkbenchAssetRelationship
+    first: Int
+    after: String
+  ): WorkbenchAssetConnection!
+}
+```
+
+### `Experience` (extension)
+
+```graphql
+extend type Experience {
+  """
+  This Experience's Workbench, resolved (and created on first access) by its stable `key`.
+  """
+  workbench: Workbench!
+}
+```
+
+### `DesignSystem` (extension)
+
+```graphql
+extend type DesignSystem {
+  """
+  This Design System's Workbench, resolved (and created on first access) by its `id`.
+  """
+  workbench: Workbench!
+}
+```
+
+### `WorkbenchAssetImportInput`
+
+```graphql
+"""Input for `workbenchAssetImport`."""
+input WorkbenchAssetImportInput {
+  """The Workbench to import into."""
+  workbenchId: ID!
+  """The Asset to import, owned elsewhere."""
+  assetId: ID!
+}
+```
+
+### `WorkbenchAssetImportPayload`
+
+```graphql
+"""Payload returned by `workbenchAssetImport`."""
+type WorkbenchAssetImportPayload {
+  """The newly created `IMPORTED` membership."""
+  workbenchAsset: WorkbenchAsset!
+}
+```
+
+### `WorkbenchAssetAdoptOwnedInput`
+
+```graphql
+"""Input for `workbenchAssetAdoptOwned`."""
+input WorkbenchAssetAdoptOwnedInput {
+  """The Workbench that should take ownership of the Asset."""
+  workbenchId: ID!
+  """
+  The project-library Asset to adopt as `OWNED`, transferring its ownership to the Workbench.
+  """
+  assetId: ID!
+  """Optional logical path to assign the membership within the Workbench."""
+  path: String
+}
+```
+
+### `WorkbenchAssetAdoptOwnedPayload`
+
+```graphql
+"""Payload returned by `workbenchAssetAdoptOwned`."""
+type WorkbenchAssetAdoptOwnedPayload {
+  """The `OWNED` membership after adoption."""
+  workbenchAsset: WorkbenchAsset!
+}
+```
+
+### `WorkbenchAssetRemoveInput`
+
+```graphql
+"""Input for `workbenchAssetRemove`."""
+input WorkbenchAssetRemoveInput {
+  """The Workbench to remove the Asset from."""
+  workbenchId: ID!
+  """The Asset to remove."""
+  assetId: ID!
+}
+```
+
+### `WorkbenchAssetRemovePayload`
+
+```graphql
+"""Payload returned by `workbenchAssetRemove`."""
+type WorkbenchAssetRemovePayload {
+  """
+  The Asset id that was removed from the Workbench. Only the join is guaranteed removed; the Asset itself is also soft-deleted when the membership was `OWNED`.
+  """
+  removedAssetId: ID!
+}
+```