picked 0.0.101 → 0.0.102-next.2

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

@@ -6,13 +6,14 @@ generated: true
 
 # Feature schema
 
-The operations and types that `feature.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
 
 ### `feature`
 
-Fetch a single feature by ID and workspace ID. Requires authentication.
+Reads a feature flag by its ID and workspace.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 feature(input: FeatureInput!): Feature @auth
@@ -20,8 +21,9 @@ feature(input: FeatureInput!): Feature @auth
 
 ### `features`
 
-List features in a workspace. Filter by name with `search` (case-insensitive
-substring) and order with `sortKey` (default `NAME`) plus `reverse`.
+Lists the feature flags in a workspace. `search` matches a case-insensitive substring of the
+name; `sortKey` and `reverse` set the order.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 features(workspaceId: ID!, first: Int, after: String, last: Int, before: String, search: String, sortKey: FeatureSortKeys = NAME, reverse: Boolean = false): FeatureConnection! @auth
@@ -31,7 +33,8 @@ features(workspaceId: ID!, first: Int, after: String, last: Int, before: String,
 
 ### `featureCreate`
 
-Create a new feature. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Creates a feature flag in a workspace.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 featureCreate(input: FeatureCreateInput!): FeatureCreatePayload! @auth
@@ -39,7 +42,8 @@ featureCreate(input: FeatureCreateInput!): FeatureCreatePayload! @auth
 
 ### `featureUpdate`
 
-Update a feature. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Updates a feature flag.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 featureUpdate(input: FeatureUpdateInput!): FeatureUpdatePayload! @auth
@@ -47,7 +51,8 @@ featureUpdate(input: FeatureUpdateInput!): FeatureUpdatePayload! @auth
 
 ### `featureDelete`
 
-Delete a feature. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Deletes a feature flag.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 featureDelete(input: FeatureDeleteInput!): FeatureDeletePayload! @auth
@@ -58,7 +63,7 @@ featureDelete(input: FeatureDeleteInput!): FeatureDeletePayload! @auth
 ### `FeatureValueType`
 
 ```graphql
-"""What a feature's variants serve. Fixed when the feature is created."""
+"""What a feature flag's arms serve. Fixed when the feature is created."""
 enum FeatureValueType {
   """
   Two arms. The visitor's site receives `true` or `false`, split by `weight`.
@@ -75,34 +80,25 @@ enum FeatureValueType {
 
 ```graphql
 """
-One arm of a feature.
-
-`key` is the stable identity: it is what the visitor's browser stores, what
-reporting records, and what a preview override names. It is also the order
-allocation runs in, so `name`, `value` and `weight` are all freely editable
-without moving a visitor between arms.
-
-Every feature has a control arm keyed `false` serving `false`. A `BOOLEAN`
-feature has exactly one more, keyed `true`, derived from `weight` rather than
-stored.
+One arm of a feature flag. Every feature has a control arm keyed `false` that serves `false`; a
+`BOOLEAN` feature has exactly one more, keyed `true` and derived from `weight`.
 """
 type FeatureVariant {
   """
-  Stable identity, unique within the feature. `true` and `false` are reserved for the structural arms.
+  The stable identifier of the arm, unique within the feature. The visitor's browser, reports and
+  preview overrides name the arm by it, and allocation orders arms by it, so `name`, `value` and
+  `weight` change without moving a visitor between arms. `true` and `false` are reserved.
   """
   key: String!
-  """
-  Display label. Shown in the dashboard and as the arm's label in reports.
-  """
+  """The label of the arm in the dashboard and in reports."""
   name: String!
   """
-  What the visitor's site receives — a string, or `false` for the control arm.
+  What the visitor's site receives: a string, or `false` for the control arm.
   """
   value: JSON!
   """
-  Share of traffic relative to the other variants, as a whole number. Meaning is
-  relative, not absolute: `1, 1, 1` and `10, 10, 10` are the same even split.
-  Stored reduced by the greatest common divisor, so equivalent splits are equal.
+  The arm's share of traffic relative to the other arms, as a whole number: `1, 1, 1` and
+  `10, 10, 10` are the same even split. Stored reduced by the greatest common divisor.
   """
   weight: Int!
 }
@@ -112,53 +108,44 @@ type FeatureVariant {
 
 ```graphql
 """
-An A/B test feature within a workspace. SDKs consume features by `key`
-and check `enabled` / `weight` to decide whether to expose the feature
-to a given visitor.
-
-`weight` is a percentage (0-100); 100 means "always serve this feature".
-`version` increments whenever the feature is updated and is exposed to
-SDKs as a cache-busting hint.
+A feature flag: a control that decides which visitors see a change, for an A/B test or a staged release.
 """
 type Feature {
-  """Unique feature identifier."""
+  """The ID of the feature."""
   id: ID!
   """
-  Stable, human-readable key for SDK consumers (e.g. `homepage-banner-v2`).
+  The stable identifier of the feature, unique within its workspace, such as `homepage-banner-v2`.
   """
   key: String!
-  """Display name of the feature."""
+  """The name of the feature."""
   name: String!
-  """Optional description of the feature."""
+  """A description of the feature. Null when none is set."""
   description: String
   """
-  Whether the feature is enabled (`false` disables it for all visitors regardless of `weight`).
+  Whether the feature is on. When false, it is off for every visitor, whatever `weight` says.
   """
   enabled: Boolean!
   """
-  Share of visitors outside the control arm (0-100). For a `BOOLEAN` feature this
-  is the allocation input. For a `TEXT` feature it is derived from the variant
-  weights and carried for clients that predate variants; such a client puts the
-  right share of visitors in control, and current clients allocate from `variants`.
+  The percentage of visitors outside the control arm, from 0 to 100. A `BOOLEAN` feature allocates
+  from it; a `TEXT` feature derives it from the arm weights.
   """
   weight: Int!
-  """What this feature's variants serve. Fixed at creation."""
+  """What the feature's arms serve."""
   valueType: FeatureValueType!
   """
-  The feature's arms. Always at least two, and the last is always the control arm
-  keyed `false`. A `BOOLEAN` feature's pair is derived from `weight` rather than
-  stored, so every consumer sees one shape regardless of value type.
+  The arms of the feature: at least two, with the control arm keyed `false` last. A `BOOLEAN`
+  feature's pair is derived from `weight`, so every value type has the same shape.
   """
   variants: [FeatureVariant!]!
   """
-  Version number, incremented on each update. Cache-busting hint for SDKs.
+  A number that forms part of the SDK cache key. It increases only when `featureUpdate` sets `incrementVersion`.
   """
   version: Int!
-  """The workspace this feature belongs to."""
+  """The workspace the feature belongs to."""
   workspace: Workspace!
-  """When this feature was created."""
+  """When the feature was created."""
   createdAt: DateTime!
-  """When this feature was last updated."""
+  """When the feature last changed."""
   updatedAt: DateTime!
 }
 ```
@@ -166,9 +153,9 @@ type Feature {
 ### `FeatureEdge`
 
 ```graphql
-"""Edge type for `FeatureConnection`."""
+"""A feature in a page of results."""
 type FeatureEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The feature."""
   node: Feature!
@@ -178,13 +165,13 @@ type FeatureEdge {
 ### `FeatureConnection`
 
 ```graphql
-"""Relay-style connection of features."""
+"""A page of features."""
 type FeatureConnection {
-  """List of feature edges."""
+  """The edges in this page."""
   edges: [FeatureEdge!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of features."""
+  """The number of features across all pages, ignoring `search`."""
   totalCount: Int!
 }
 ```
@@ -192,11 +179,11 @@ type FeatureConnection {
 ### `FeatureInput`
 
 ```graphql
-"""Input for looking up a single feature."""
+"""The input of `feature`."""
 input FeatureInput {
-  """Feature ID."""
+  """The ID of the feature."""
   id: ID!
-  """Workspace ID the feature belongs to."""
+  """The ID of the workspace the feature belongs to."""
   workspaceId: ID!
 }
 ```
@@ -205,21 +192,19 @@ input FeatureInput {
 
 ```graphql
 """
-One arm, as submitted. Omit `key` on a new variant and it is derived from `name`.
-The control arm is submitted like any other, keyed `false` with value `false`, and
-must come last.
+One arm of a feature flag, as input. Submit the control arm keyed `false` with value `false`, last.
 """
 input FeatureVariantInput {
-  """Stable identity. Derived from `name` when omitted."""
+  """The stable identifier of the arm. Derived from `name` when omitted."""
   key: String
-  """Display label."""
+  """The label of the arm."""
   name: String!
   """
-  What the visitor's site receives — a string, or `false` for the control arm.
+  What the visitor's site receives: a string, or `false` for the control arm.
   """
   value: JSON!
   """
-  Share of traffic relative to the other variants. Reduced by the greatest common divisor on save.
+  The arm's share of traffic relative to the other arms. Reduced by the greatest common divisor on save.
   """
   weight: Int!
 }
@@ -228,28 +213,30 @@ input FeatureVariantInput {
 ### `FeatureCreateInput`
 
 ```graphql
-"""Input for `featureCreate`."""
+"""The input of `featureCreate`."""
 input FeatureCreateInput {
-  """Workspace ID to create the feature in."""
+  """The ID of the workspace to create the feature in."""
   workspaceId: ID!
-  """
-  Organisation ID. Carried for authorisation; must match the workspace's organisation.
-  """
+  """Ignored. The feature belongs to the workspace's organisation."""
   organizationId: ID!
-  """Display name for the feature."""
+  """The name of the feature. At least 3 characters."""
   name: String!
-  """Optional human-readable key (auto-generated from `name` if omitted)."""
+  """
+  The stable identifier of the feature, unique within the workspace: lowercase letters, digits and
+  hyphens. Derived from `name` when omitted. It cannot change later.
+  """
   key: String
-  """Optional description."""
+  """A description of the feature. At most 500 characters."""
   description: String
-  """Whether the feature is enabled. Defaults to `false`."""
+  """Whether the feature is on. Defaults to `false`."""
   enabled: Boolean
   """
-  Traffic weight percentage (0-100). Defaults to `0`. Rejected for a `TEXT` feature, which derives its weight from `variants`.
+  The percentage of visitors outside the control arm, from 0 to 100. Defaults to `0`. Rejected for
+  a `TEXT` feature, which derives it from `variants`.
   """
   weight: Int
   """
-  What this feature's variants serve. Defaults to `BOOLEAN`. Cannot be changed after creation.
+  What the feature's arms serve. Defaults to `BOOLEAN`. It cannot change later.
   """
   valueType: FeatureValueType
   """
@@ -262,7 +249,7 @@ input FeatureCreateInput {
 ### `FeatureCreatePayload`
 
 ```graphql
-"""Payload returned by `featureCreate`."""
+"""The result of `featureCreate`."""
 type FeatureCreatePayload {
   """The created feature."""
   feature: Feature
@@ -272,31 +259,28 @@ type FeatureCreatePayload {
 ### `FeatureUpdateInput`
 
 ```graphql
-"""Input for `featureUpdate`. Omit a field to leave it unchanged."""
+"""The input of `featureUpdate`. Omit a field to keep its value."""
 input FeatureUpdateInput {
-  """Feature ID."""
+  """The ID of the feature."""
   id: ID!
-  """Workspace ID the feature belongs to."""
+  """The ID of the workspace the feature belongs to."""
   workspaceId: ID!
-  """New display name."""
+  """The name of the feature. At least 3 characters."""
   name: String
-  """New description."""
+  """A description of the feature. At most 500 characters."""
   description: String
-  """Whether the feature is enabled."""
+  """Whether the feature is on."""
   enabled: Boolean
   """
-  New traffic weight percentage (0-100). Rejected for a `TEXT` feature, which derives its weight from `variants`.
+  The percentage of visitors outside the control arm, from 0 to 100. Rejected for a `TEXT`
+  feature, which derives it from `variants`.
   """
   weight: Int
   """
-  Replaces the whole set of arms. Partial updates of a single arm are not
-  supported, because reducing weights by their greatest common divisor is a
-  property of the whole array. Rejected for a `BOOLEAN` feature.
+  The full set of arms, control last. Replaces every arm. Rejected for a `BOOLEAN` feature.
   """
   variants: [FeatureVariantInput!]
-  """
-  Whether to increment the version number. Defaults to `true` so SDKs see the change.
-  """
+  """Whether to increase `version`. Defaults to `false`."""
   incrementVersion: Boolean
 }
 ```
@@ -304,7 +288,7 @@ input FeatureUpdateInput {
 ### `FeatureUpdatePayload`
 
 ```graphql
-"""Payload returned by `featureUpdate`."""
+"""The result of `featureUpdate`."""
 type FeatureUpdatePayload {
   """The updated feature."""
   feature: Feature
@@ -314,11 +298,11 @@ type FeatureUpdatePayload {
 ### `FeatureDeleteInput`
 
 ```graphql
-"""Input for `featureDelete`."""
+"""The input of `featureDelete`."""
 input FeatureDeleteInput {
-  """Feature ID."""
+  """The ID of the feature."""
   id: ID!
-  """Workspace ID the feature belongs to."""
+  """The ID of the workspace the feature belongs to."""
   workspaceId: ID!
 }
 ```
@@ -326,9 +310,9 @@ input FeatureDeleteInput {
 ### `FeatureDeletePayload`
 
 ```graphql
-"""Payload returned by `featureDelete`."""
+"""The result of `featureDelete`."""
 type FeatureDeletePayload {
-  """ID of the deleted feature."""
+  """The ID of the deleted feature."""
   deletedFeatureId: ID
 }
 ```
@@ -336,15 +320,13 @@ type FeatureDeletePayload {
 ### `FeatureSortKeys`
 
 ```graphql
-"""
-Sort keys for `features(...)`. Pair with `reverse: true` to flip the order (`NAME` + `reverse: false` sorts A→Z; `CREATED_AT` + `reverse: true` is newest-first).
-"""
+"""The orders `features` can sort by. `reverse: true` flips each."""
 enum FeatureSortKeys {
-  """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/feedback.md

@@ -6,13 +6,13 @@ generated: true
 
 # Feedback schema
 
-The operations and types that `feedback.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.
 
 ## Mutations
 
 ### `feedbackCreate`
 
-Submit user feedback from the dashboard. Requires authentication (USER token only).
+Sends product feedback from the signed-in user to the Picked team.
 
 ```graphql
 feedbackCreate(input: FeedbackCreateInput!): FeedbackCreatePayload! @auth(only: USER)
@@ -23,19 +23,19 @@ feedbackCreate(input: FeedbackCreateInput!): FeedbackCreatePayload! @auth(only:
 ### `FeedbackTopic`
 
 ```graphql
-"""Topic categories for user feedback."""
+"""What a piece of feedback is about."""
 enum FeedbackTopic {
-  """Bug report — something doesn't work as expected."""
+  """Something does not work as expected."""
   BUG
-  """Feature request — a missing capability the user wants."""
+  """A capability the user wants."""
   FEATURE_REQUEST
-  """Improvement — feedback on an existing capability."""
+  """A change to an existing capability."""
   IMPROVEMENT
-  """Question — the user needs help."""
+  """A request for help."""
   QUESTION
-  """Navigation — feedback on the dashboard's sidebar navigation."""
+  """The dashboard's sidebar navigation."""
   NAVIGATION
-  """Other — uncategorised feedback."""
+  """Anything else."""
   OTHER
 }
 ```
@@ -43,19 +43,17 @@ enum FeedbackTopic {
 ### `FeedbackSentiment`
 
 ```graphql
-"""
-Sentiment rating for user feedback. Optional; clients can omit when they don't prompt for sentiment.
-"""
+"""How the user feels about what their feedback describes."""
 enum FeedbackSentiment {
-  """Very negative — user is frustrated or angry."""
+  """Frustrated or angry."""
   VERY_NEGATIVE
-  """Negative — user is dissatisfied."""
+  """Dissatisfied."""
   NEGATIVE
-  """Neutral — user is indifferent."""
+  """Indifferent."""
   NEUTRAL
-  """Positive — user is satisfied."""
+  """Satisfied."""
   POSITIVE
-  """Very positive — user is delighted."""
+  """Delighted."""
   VERY_POSITIVE
 }
 ```
@@ -63,31 +61,29 @@ enum FeedbackSentiment {
 ### `FeedbackCreateInput`
 
 ```graphql
-"""
-Input for `feedbackCreate` — submit a feedback message from the dashboard.
-"""
+"""The input of `feedbackCreate`."""
 input FeedbackCreateInput {
-  """The feedback message content."""
+  """The feedback text: 1 to 5,000 characters, not blank."""
   message: String!
-  """The topic category of the feedback."""
+  """What the feedback is about."""
   topic: FeedbackTopic!
-  """Optional sentiment rating."""
+  """How the user feels. Omit when the client does not ask."""
   sentiment: FeedbackSentiment
   """
-  The page path where feedback was submitted (e.g. `/orgs/acme/projects/123`).
+  The dashboard path the user sent the feedback from, such as `/orgs/acme/projects/123`.
   """
   pagePath: String
-  """The organisation context, if applicable."""
+  """The ID of the organisation the user was working in."""
   organizationId: ID
-  """The project context, if applicable."""
+  """The ID of the project the user was working in."""
   projectId: ID
   """
-  The Picked session id, if available — links feedback to a session recording.
+  The ID of the user's Picked session, which links the feedback to its session recording.
   """
   pickedSessionId: String
-  """The user's browser user-agent string."""
+  """The user's browser user agent."""
   userAgent: String
-  """The user's screen resolution (e.g. `1920x1080`)."""
+  """The user's screen resolution, such as `1920x1080`."""
   screenResolution: String
 }
 ```
@@ -95,9 +91,9 @@ input FeedbackCreateInput {
 ### `FeedbackCreatePayload`
 
 ```graphql
-"""Payload returned by `feedbackCreate`."""
+"""The result of `feedbackCreate`."""
 type FeedbackCreatePayload {
-  """The id of the newly created feedback row."""
+  """The ID of the feedback."""
   feedbackId: ID!
 }
 ```