feat(KNO-14970): Docs for Goals

.cursor/rules/styleguide.mdc

@@ -42,6 +42,7 @@ Here is a list of Knock concept/feature names that should not be capitalized unl
 - Messages
 - Environments
 - Audiences
+- Goals
 
 ## Case: always use sentence case
 

AGENTS.md

@@ -111,6 +111,7 @@ Here is a list of Knock concept/feature names that should not be capitalized unl
 - Messages
 - Environments
 - Audiences
+- Goals
 
 ## Case: always use sentence case
 

content/ai/agent.mdx

@@ -15,7 +15,7 @@ section: AI
 
 The Knock agent is an AI-powered assistant built into the Knock dashboard.
 
-You can use it to do anything you'd normally do in the dashboard, including create workflows, templates, guides, broadcasts, and partials. You can also use the Knock agent to learn about Knock concepts and inspect existing resources.
+You can use it to do anything you'd normally do in the dashboard, including create workflows, templates, guides, broadcasts, partials, and goals. You can also use the Knock agent to learn about Knock concepts and inspect existing resources.
 
 <Callout
   type="info"
@@ -49,11 +49,11 @@ You can optionally use the Knock agent directly from your Slack workspace using
 
 ### Read and inspect resources
 
-The agent has full access to all of your Knock resources, including workflows, broadcasts, partials, email layouts, audiences, message types, and guides.
+The agent has full access to all of your Knock resources, including workflows, broadcasts, partials, email layouts, audiences, message types, guides, and goals.
 
 ### Create and modify resources
 
-The agent can create or update workflows, broadcasts, partials, email layouts, audiences, message types, and guides using dedicated tools. Each maps to a customer messaging primitive you manage in the dashboard.
+The agent can create or update workflows, broadcasts, partials, email layouts, audiences, message types, guides, and goals using dedicated tools. Each maps to a customer messaging primitive you manage in the dashboard.
 
 ### Bulk updates and refactors
 

content/cli/overview.mdx

@@ -165,6 +165,7 @@ When you use `knock pull`, resources will be grouped by resource type within sub
 {/* prettier-ignore */}
 <PreTextDiagram description="Recommended directory structure for Knock resources">
 {`./knock/
+├── audiences/
 ├── guides/
 ├── layouts/
 ├── message-types/

content/concepts/broadcasts.mdx

@@ -96,6 +96,8 @@ Broadcasts can optionally be scheduled to send at a specific time. When a broadc
 
 Broadcasts produce messages, exactly as workflows do. As such, messages sent as part of a broadcast will be visible in the **Analytics** page within the Knock dashboard. Additionally, broadcast engagement metrics are available in any [connected data warehouses](/integrations/extensions/data-sync).
 
+You can also [attach a goal](/concepts/goals) to a broadcast to measure attributed completions against a defined outcome.
+
 Sent broadcasts include a recipient summary that highlights key delivery and engagement metrics, including:
 
 - **Sent**: The number of messages that were successfully sent to the delivery provider.

content/concepts/goals.mdx

@@ -0,0 +1,196 @@
+---
+title: Goals
+description: Learn how to define measurable outcomes, attach them to messaging, and track attributed completions in Knock.
+tags:
+  [
+    "goals",
+    "attribution",
+    "conversions",
+    "completions",
+    "outcomes",
+    "analytics",
+    "workflows",
+    "broadcasts",
+    "guides",
+  ]
+section: Concepts
+---
+
+A goal is a reusable, environment-scoped outcome that you identify as having special business meaning. For example, you might define a "Customer activated" goal that completes when a user creates their first channel or starts an agent session.
+
+Each goal has an immutable `key`, a title, an optional description, and a condition that defines when the goal is met. When a recipient meets the goal condition, Knock records a **completion**. When that completion can be credited to a [workflow](/concepts/workflows), [broadcast](/concepts/broadcasts), or [guide](/concepts/guides) that has the goal attached, Knock also records an **attributed completion**.
+
+Use goals to:
+
+- Tell Knock what you are trying to accomplish with customer messaging, beyond opens and clicks.
+- Measure how often an outcome happens, and how often messaging can be credited for it.
+- Give the [Knock agent](/ai/agent) context about intent so it can propose and improve messaging against those outcomes.
+
+## Creating a goal
+
+To create a goal, navigate to the **Goals** page in the Knock dashboard, then create a new goal. Set:
+
+- **Key.** An immutable, environment-unique identifier for the goal.
+- **Title.** A human-readable name for the goal. In the Management API, this field is `name`.
+- **Description.** Optional context about what the goal means for your business.
+- **Condition.** The event that must happen for Knock to record a completion. See [Goal conditions](#goal-conditions).
+
+Goals are scoped to an [environment](/concepts/environments). When you save a goal, Knock publishes it. Goals do not use the commit-and-promote model that workflows and other versioned resources use. Goal definition changes create a new goal version and keep a history of prior versions.
+
+### Cloning a goal
+
+You can [clone a goal](/version-control/environments#clone-resources-across-environments) into the same environment or another environment. Cloning copies the latest version of the goal (key, title, description, and condition). It does **not** copy attachments to workflows, broadcasts, or guides.
+
+Goals are not promotable between environments. To use the same goal definition elsewhere, clone it.
+
+### Archiving a goal
+
+Archiving a goal soft-deletes it. Knock stops calculating new completions and attributions for the archived goal, and retains historical versions and completions. You cannot un-archive a goal.
+
+## Goal conditions
+
+A goal condition defines what must happen for Knock to record a completion. Goal conditions reuse a subset of the event model from the [wait for event function](/designing-workflows/wait-for-event-function), with one important difference: Knock evaluates goal conditions **globally for a recipient** when the event happens, not inside a workflow run. Match filters therefore use `event` and `recipient` only. They do not have access to workflow run state such as `data`, `refs`, or `run`.
+
+Supported event types:
+
+| Event type | Description | Match conditions |
+| --- | --- | --- |
+| **Integration source** | An event from a connected [integration source](/integrations/sources/overview), such as Segment or Stripe. | Optional. Filter on event properties under `event.*`. |
+| **Audience entry / exit** | A recipient enters or exits an [audience](/concepts/audiences). | Not required. |
+| **Recipient updated** | A [user](/concepts/users) property changes. | Required. Filter on recipient properties under `recipient.*`. |
+
+For supported operators, see the [conditions docs](/concepts/conditions).
+
+Goal conditions do not support message events, workflow run events, wait timeouts, or on-match / on-timeout controls. Those remain wait for event–only concepts.
+
+### Example: recipient property updated
+
+```json
+{
+  "event": {
+    "event_type": "recipient",
+    "event_key": "updated"
+  },
+  "match_conditions": [
+    {
+      "operator": "and",
+      "conditions": [
+        {
+          "variable": "recipient.is_paid",
+          "operator": "equal_to",
+          "argument": "true"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Example: source event with a property filter
+
+```json
+{
+  "event": {
+    "event_type": "integration_source",
+    "event_key": "order.completed",
+    "integration_source_key": "stripe"
+  },
+  "match_conditions": [
+    {
+      "operator": "and",
+      "conditions": [
+        {
+          "variable": "event.data.amount",
+          "operator": "greater_than",
+          "argument": "0"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Attaching a goal to messaging
+
+You can attach a goal to a [workflow](/concepts/workflows), [broadcast](/concepts/broadcasts), or [guide](/concepts/guides):
+
+- One goal can be attached to many messaging resources.
+- Each messaging resource can have at most one attached goal.
+
+A goal attachment includes:
+
+- **Goal key.** The key of the goal to attach.
+- **Attribution window.** The number of days after the attribution anchor during which a completion can be credited to the resource. Must be between 7 and 30 days (day granularity). Defaults to 7 days.
+
+The attachment lives on the messaging resource's version. Attaching, detaching, or changing the attribution window creates a new version of that workflow, broadcast, or guide, and follows that resource's [commit](/version-control/commits) model.
+
+## Attribution
+
+When a recipient meets a goal condition, Knock records a **completion**. If the goal is attached to one or more messaging resources, Knock then decides whether the completion is an **attributed completion**.
+
+### Attribution window and anchor
+
+The attribution window is set per attachment when you attach the goal. The window starts at a per-recipient **attribution anchor**:
+
+- **Workflows and broadcasts.** First message sent to the recipient for the most recent run of that resource.
+- **Guides.** Guide message created for the recipient (this happens asynchronously).
+
+A resource is **eligible for attribution** when its attribution anchor falls within the attachment's window relative to the completion time.
+
+### Last-touch attribution
+
+If multiple attached resources are eligible for the same completion, Knock attributes the completion to the resource that messaged the recipient most recently (last touch).
+
+### Example: attribution window
+
+Goal 1 is attached to Workflow A (7-day window) and Guide B (30-day window). Recipient X received messaging from:
+
+- Workflow A: one run that sent its first message 8 days ago (and another message 1 day ago on that same run)
+- Guide B: 6 days ago
+
+Is Workflow A inside its attribution window?
+
+- No. The attribution anchor is the **first** message sent on the most recent Workflow A run (8 days ago), and the attachment has a 7-day window.
+
+### Example: last touch
+
+Goal 1 is attached to Workflow A and Guide B. Both attachments have a 30-day window. Recipient X received messaging from:
+
+- Workflow A: first message 8 days ago, most recent message 1 day ago
+- Guide B: 6 days ago
+
+Both resources are inside their windows. Last touch was Workflow A, so Knock attributes the completion to **Workflow A**.
+
+## Reporting
+
+On the **Goals** page in the dashboard, you can view all goals in the current environment. The list shows a rolling **30-day activity** sparkline of attributed completions for each goal (day-level granularity). Goals with no attributed completions in the last 30 days omit the sparkline.
+
+Open a goal to see:
+
+- **Overview.** Time series of completions and attributed completions for a selected range, with totals and completion rate. You can break the series down by goal version or by messaging resource, and see attributed completions per attached resource.
+- **Completions log.** A paginated list of individual completions and attributed completions for the same range as the overview. Each row includes the recipient, completion time, triggering event, and (when attributed) the winning messaging resource and message.
+
+Attributed completions are a strict subset of completions. Attribution for analytics can take up to 15 minutes to appear after a completion.
+
+Resource-level conversion metrics on workflow, broadcast, and guide analytics pages are not included in this release. Use the goal detail page and resource breakdowns instead.
+
+## Goals and the Knock agent
+
+The [Knock agent](/ai/agent) has full read access to goals and their fields. The agent can propose and create goals, reuse an existing goal, or define a new one when building or improving messaging. Goal context helps the agent reason about what your messaging is trying to accomplish, even when a goal is not yet attached to a resource.
+
+## Managing goals programmatically
+
+You can create, update, clone, and archive goals, and attach them to messaging resources, with the [Management API](/mapi-reference/goals).
+
+Goal upserts publish on save. Unlike workflows and guides, the goals upsert endpoint does not accept a commit parameter. Attachments are stored on the workflow, broadcast, or guide as a `goal_attachment` (`goal_key` and `attribution_window_days`).
+
+## Limitations
+
+The following are not available in this release:
+
+- Using a goal as exit criteria to cancel an in-flight workflow run.
+- Tenant-property goal conditions.
+- Attaching more than one goal to a single messaging resource.
+- Goal conversion metrics on the workflow, broadcast, or guide analytics pages.
+- Promoting goals between environments (clone a goal instead).
+- Managing goals with the Knock CLI (coming in a later release).

content/concepts/guides.mdx

@@ -37,6 +37,8 @@ Guides include an analytics summary that highlights key metrics over the last N
 
 To learn more, see our [message status documentation](/send-notifications/message-statuses).
 
+You can also [attach a goal](/concepts/goals) to a guide to measure attributed completions against a defined outcome.
+
 ## Guides pricing
 
 Guides usage is priced using **engaged users**, which is the distinct number of users who have **seen** or **engaged** with a guide in the billing period.

content/concepts/overview.mdx

@@ -123,3 +123,9 @@ Variables within Knock let you set shared constants or secrets that you can use
 Audiences are user segments that you can notify. You can bring audiences into Knock programmatically with our API or a supported reverse-ETL source.
 
 [Learn more →](/concepts/audiences)
+
+## Goals
+
+Goals are measurable outcomes you define in Knock, such as a user activating or converting to paid. You attach goals to workflows, broadcasts, and guides to track completions and attributed completions.
+
+[Learn more →](/concepts/goals)

content/concepts/workflows.mdx

@@ -64,6 +64,10 @@ All changes to workflows, including changes made to the templates inside of a wo
 
 Read more about [environments](/version-control/environments) and [versioning](/version-control/commits) in Knock.
 
+### Goals
+
+You can [attach a goal](/concepts/goals) to a workflow to measure when recipients complete a defined outcome and whether that completion can be attributed to the workflow.
+
 ### Workflow status
 
 Each workflow has an `Active`/`Inactive` status that is displayed in your dashboard's **Workflows** section. The status defaults to `Active` and can be set by clicking on the workflow and using the **Status** selector in the **Details** section of the **Overview** tab.

content/designing-workflows/wait-for-event-function.mdx

@@ -17,6 +17,8 @@ section: Designing workflows
 
 A wait for event function pauses a workflow or broadcast until a matching event is received, or until a configured wait time expires. Use it when the next step in your workflow or broadcast should depend on something that happens after the run starts — such as a payment completing in an external system, a message being delivered, another workflow finishing for the same recipient, an audience membership change, or a recipient property update.
 
+[Goal conditions](/concepts/goals#goal-conditions) reuse a subset of this event model (integration source, audience entry/exit, and recipient updated) to define measurable outcomes outside of a workflow run.
+
 ## How it works
 
 When a workflow run reaches a wait for event step, Knock pauses execution and registers a durable wait for the configured event. The workflow stays paused until one of the following happens:

content/developer-tools/management-api.mdx

@@ -12,6 +12,7 @@ You can use the Knock management API to:
 - Create, update and manage your [email layouts](/integrations/email/layouts).
 - Create and manage the [translations](/template-editor/translations) used by your notification templates.
 - Create, update, and manage your [partials](/template-editor/partials).
+- Create, update, clone, and archive [goals](/concepts/goals), and attach them to workflows, broadcasts, and guides.
 - Commit and promote changes between your Knock environments.
 
 [View management API reference](/mapi)

content/getting-started/what-is-knock.mdx

@@ -389,6 +389,7 @@ There is a lot more to learn about Knock, and our [concepts overview page](/conc
 - Creating advanced messaging logic using [subscriptions](/concepts/subscriptions) and [schedules](/concepts/schedules).
 - Integrating Knock with your application's data model, using [tenants](/concepts/tenants) and [objects](/concepts/objects) to power customized experiences.
 - Using [the template editor](/template-editor/overview) to standardize messaging templates across providers.
+- Defining [goals](/concepts/goals) to measure outcomes and attribute completions to your messaging.
 
 #### Developer tools
 

content/version-control/environments.mdx

@@ -163,13 +163,16 @@ You can clone the following resources across environments:
 - Message types
 - Email layouts
 - Audiences
+- Goals
 - Partials
 - Translations
 - Reusable requests
 - Source event mappings
 
 Archived resources cannot be cloned.
 
+Goals are cloned, not promoted. Cloning a goal copies its latest definition into the destination environment and does not copy attachments to workflows, broadcasts, or guides. See [goals](/concepts/goals) for more detail.
+
 ### Clone vs promote
 
 Clone and promote solve different problems:

data/sidebars/mapiOverviewSidebar.ts

@@ -9,6 +9,7 @@ export const RESOURCE_ORDER = [
   "broadcasts",
   "email_layouts",
   "audiences",
+  "goals",
   "partials",
   "guides",
   "message_types",

data/sidebars/platformSidebar.ts

@@ -36,6 +36,7 @@ export const PLATFORM_SIDEBAR: SidebarSection[] = [
       { slug: "/objects", title: "Objects" },
       { slug: "/subscriptions", title: "Subscriptions" },
       { slug: "/audiences", title: "Audiences" },
+      { slug: "/goals", title: "Goals" },
       { slug: "/schedules", title: "Schedules" },
       { slug: "/messages", title: "Messages" },
       { slug: "/conditions", title: "Conditions" },

data/specs/mapi/customizations.yml

@@ -92,6 +92,10 @@ resources:
     name: Audiences
     description: |-
       [Audiences](/concepts/audiences) are user segments that you can use to target users for workflows, guides, and broadcasts.
+  goals:
+    name: Goals
+    description: |-
+      [Goals](/concepts/goals) are measurable outcomes you define in Knock and attach to workflows, broadcasts, and guides for completion and attribution tracking. Goal upserts publish immediately and do not accept a commit parameter. Clone a goal to copy it into another environment; goals are not promotable.
   data_sources:
     name: Data sources
     description: |-

data/specs/mapi/stainless.yml

@@ -277,6 +277,19 @@ resources:
       upsert: put /v1/audiences/{audience_key}
       validate: put /v1/audiences/{audience_key}/validate
       list: get /v1/audiences
+  goals:
+    models:
+      goal: "#/components/schemas/Goal"
+      goal_condition: "#/components/schemas/GoalCondition"
+      goal_attachment: "#/components/schemas/GoalAttachment"
+      clone_goal_request: "#/components/schemas/CloneGoalRequest"
+    methods:
+      archive: delete /v1/goals/{goal_key}
+      retrieve: get /v1/goals/{goal_key}
+      upsert: put /v1/goals/{goal_key}
+      validate: put /v1/goals/{goal_key}/validate
+      list: get /v1/goals
+      clone: post /v1/goals/{goal_key}/clone
 settings:
   disable_mock_tests: true
   license: Apache-2.0