From 388a4b949d177cacf12bfd7a6d4d327f6758d900 Mon Sep 17 00:00:00 2001
From: Tim Conley <timothy.conley@temporal.io>
Date: Wed, 2 Sep 2026 13:50:29 -0700
Subject: [PATCH] docs: add System Nexus WIT documentation

---
 nexus/deps/nexus-temporal-types/model.wit | 2 ++
 nexus/workflow-service.wit                | 6 ++++++
 2 files changed, 8 insertions(+)

diff --git a/nexus/deps/nexus-temporal-types/model.wit b/nexus/deps/nexus-temporal-types/model.wit
index 9909d34c6..f7d2ebd64 100644
--- a/nexus/deps/nexus-temporal-types/model.wit
+++ b/nexus/deps/nexus-temporal-types/model.wit
@@ -177,8 +177,10 @@ interface model {
   ///   typescript-import="@temporalio/common"
   type workflow-id-conflict-policy = placeholder;
 
+  /// @nexus.doc "Static metadata for a workflow execution."
   /// @nexus.proto "temporal.api.sdk.v1.UserMetadata" typescript-import="@temporalio/proto"
   /// @nexus.flatten-in-api
+  /// @nexus.experimental
   record user-metadata {
     /// @nexus.doc "Single-line fixed summary for the workflow execution that may appear in UI and CLI. This can be in single-line Temporal Markdown format."
     /// @nexus.proto-field "summary"
diff --git a/nexus/workflow-service.wit b/nexus/workflow-service.wit
index 9714e40cf..c4a7bf5e9 100644
--- a/nexus/workflow-service.wit
+++ b/nexus/workflow-service.wit
@@ -89,12 +89,15 @@ interface workflow-service {
     /// @nexus.doc "Amount of time to wait before starting the workflow. This does not work with cron-schedule."
     /// @nexus.proto-field "workflow_start_delay"
     start-delay: option<duration>,
+    /// @nexus.doc "Static metadata for the workflow execution."
     user-metadata: option<user-metadata>,
     /// @nexus.source python="workflow_namespace()" typescript="workflowNamespace()" go="workflow.GetInfo(ctx).Namespace" dotnet="TemporalWorkflowContext.WorkflowNamespace()"
+    /// @nexus.doc "Namespace of the workflow execution."
     namespace: string,
     /// @nexus.omit
     control: placeholder,
     /// @nexus.api-omit
+    /// @nexus.doc "Headers for the request."
     /// @nexus.proto-field "header"
     headers: option<header>,
     /// @nexus.omit
@@ -103,10 +106,13 @@ interface workflow-service {
     time-skipping-config: placeholder,
   }
 
+  /// @nexus.doc "Result of signaling a workflow and starting it if needed."
   /// @nexus.experimental
   /// @nexus.proto "temporal.api.workflowservice.v1.SignalWithStartWorkflowExecutionResponse" typescript-import="@temporalio/proto"
   record signal-with-start-workflow-response {
+    /// @nexus.doc "Run ID of the started workflow."
     run-id: option<string>,
+    /// @nexus.doc "Whether the workflow was started."
     started: option<bool>,
     /// @nexus.omit
     signal-link: placeholder,