Update docs

Author: julianna-ciq

website/docs/api/ref/Channel.md

@@ -33,7 +33,7 @@ interface Channel {
   displayMetadata?: DisplayMetadata;
 
   // functions
-  broadcast(context: Context): Promise<void>;
+  broadcast(context: Context, metadata?: AppProvidableContextMetadata): Promise<void>;
   getCurrentContext(contextType?: string): Promise<Context|null>;
   addContextListener(contextType: string | null, handler: ContextHandler): Promise<Listener>;
   clearContext(contextType?: string): Promise<void>;
@@ -430,7 +430,7 @@ var listener = await myChannel.AddEventListener(null, (event) => {
 <TabItem value="ts" label="TypeScript/JavaScript">
 
 ```ts
-public broadcast(context: Context): Promise<void>;
+public broadcast(context: Context, metadata?: AppProvidableContextMetadata): Promise<void>;
 ```
 
 </TabItem>

website/docs/api/ref/DesktopAgent.md

@@ -22,19 +22,19 @@ For details of how implementations of the `DesktopAgent` are made available to a
 ```ts
 interface DesktopAgent {
   // apps
-  open(app: AppIdentifier, context?: Context): Promise<AppIdentifier>;
+  open(app: AppIdentifier, context?: Context, metadata?: AppProvidableContextMetadata): Promise<AppIdentifier>;
   findInstances(app: AppIdentifier): Promise<Array<AppIdentifier>>;
   getAppMetadata(app: AppIdentifier): Promise<AppMetadata>;
 
   // context
-  broadcast(context: Context): Promise<void>;
+  broadcast(context: Context, metadata?: AppProvidableContextMetadata): Promise<void>;
   addContextListener(contextType: string | null, handler: ContextHandler): Promise<Listener>;
 
   // intents
   findIntent(intent: string, context?: Context, resultType?: string): Promise<AppIntent>;
   findIntentsByContext(context: Context, resultType?: string): Promise<Array<AppIntent>>;
-  raiseIntent(intent: string, context: Context, app?: AppIdentifier): Promise<IntentResolution>;
-  raiseIntentForContext(context: Context, app?: AppIdentifier): Promise<IntentResolution>;
+  raiseIntent(intent: string, context: Context, app?: AppIdentifier, metadata?: AppProvidableContextMetadata): Promise<IntentResolution>;
+  raiseIntentForContext(context: Context, app?: AppIdentifier, metadata?: AppProvidableContextMetadata): Promise<IntentResolution>;
   addIntentListener(intent: string, handler: IntentHandler): Promise<Listener>;
 
   // channels
@@ -190,7 +190,7 @@ Context broadcasts are primarily received from apps that are joined to the same
 
 Context may also be received via this listener if the application was launched via a call to  [`fdc3.open`](#open), where context was passed as an argument. In order to receive this, applications SHOULD add their context listener as quickly as possible after launch, or an error MAY be returned to the caller and the context may not be delivered. The exact timeout used is set by the Desktop Agent implementation, but MUST be at least 15 seconds.
 
-Optional metadata about each context message received, including the app that originated the message, MUST be provided by the Desktop Agent implementation.
+Optional metadata about each context message received, including the app that originated the message, SHOULD be provided by the Desktop Agent implementation.
 
 Adding multiple context listeners on the same or overlapping types (i.e. specific `contextType` and `null` type) MUST be allowed, and MUST trigger all ContextHandlers when a relevant context type is broadcast on the current user channel. Please note, that this behavior differs from [`fdc3.addIntentListener`](#addintentlistener) call; refer to the relevant documentation for more details. 
 
@@ -367,7 +367,7 @@ The Desktop Agent MUST reject the promise returned by the `getResult()` function
 
 The [`PrivateChannel`](PrivateChannel) type is provided to support synchronization of data transmitted over returned channels, by allowing both parties to listen for events denoting subscription and unsubscription from the returned channel. `PrivateChannels` are only retrievable via raising an intent.
 
-Optional metadata about each intent & context message received, including the app that originated the message, MUST be provided by the Desktop Agent implementation.
+Optional metadata about each intent & context message received, including the app that originated the message, SHOULD be provided by the Desktop Agent implementation.
 
  Adding multiple intent listeners on the same type MUST be rejected with the [`ResolveError.IntentListenerConflict`](Errors#resolveerror), unless the previous listener was removed first though [`listener.unsubscribe`](Types#unsubscribe)
 
@@ -482,7 +482,7 @@ listenerResult := <-desktopAgent.AddIntentListener("fdc3.contact", func(context
 <TabItem value="ts" label="TypeScript/JavaScript">
 
 ```ts
-broadcast(context: Context): Promise<void>;
+broadcast(context: Context, metadata?: AppProvidableContextMetadata): Promise<void>;
 ```
 
 </TabItem>
@@ -1683,7 +1683,7 @@ listenerResult := <-desktopAgent.AddContextListener("", func(context IContext, c
 <TabItem value="ts" label="TypeScript/JavaScript">
 
 ```ts
-open(app: AppIdentifier, context?: Context): Promise<AppIdentifier>;
+open(app: AppIdentifier, context?: Context, metadata?: AppProvidableContextMetadata): Promise<AppIdentifier>;
 ```
 
 </TabItem>
@@ -1771,7 +1771,7 @@ instanceIdentifierResult := <-desktopAgent.Open(appIdentifier, &context)
 <TabItem value="ts" label="TypeScript/JavaScript">
 
 ```ts
-raiseIntent(intent: string, context: Context, app?: AppIdentifier): Promise<IntentResolution>;
+raiseIntent(intent: string, context: Context, app?: AppIdentifier, metadata?: AppProvidableContextMetadata): Promise<IntentResolution>;
 ```
 
 </TabItem>
@@ -1909,7 +1909,7 @@ resolutionResult := <-desktopAgent.RaiseIntent("intentName", context, nil);
 <TabItem value="ts" label="TypeScript/JavaScript">
 
 ```ts
-raiseIntentForContext(context: Context, app?: AppIdentifier): Promise<IntentResolution>;
+raiseIntentForContext(context: Context, app?: AppIdentifier, metadata?: AppProvidableContextMetadata): Promise<IntentResolution>;
 ```
 
 </TabItem>

website/docs/api/ref/Metadata.md

@@ -263,7 +263,7 @@ type ContextMetadata struct {
 </TabItem>
 </Tabs>
 
-Metadata relating to a context or intent & context received through the `addContextListener` and `addIntentListener` functions. Currently identifies the app that originated the context or intent message.
+Metadata relating to a context or intent and context received through the `addContextListener` and `addIntentListener` functions. Can include timestamp, security, observability, or other information.
 
 [`@experimental`](../../fdc3-compliance#experimental-features) Introduced in FDC3 2.0 and may be refined by further changes outside the normal FDC3 versioning policy.
 

website/docs/api/ref/Types.md

@@ -161,7 +161,7 @@ This means that it must at least have a `type` property that indicates what type
 <TabItem value="ts" label="TypeScript/JavaScript">
 
 ```ts
-type ContextHandler = (context: Context, metadata?: ContextMetadata) => void;
+type ContextHandler = (context: Context, metadata?: DesktopAgentProvidableContextMetadata) => void;
 ```
 
 </TabItem>
@@ -239,7 +239,7 @@ type DesktopAgentIdentifier struct {
 <TabItem value="ts" label="TypeScript/JavaScript">
 
 ```ts
-type IntentHandler = (context: Context, metadata?: ContextMetadata) => Promise<IntentResult> | void;
+type IntentHandler = (context: Context, metadata?: DesktopAgentProvidableContextMetadata) => Promise<IntentResult> | void;
 ```
 
 </TabItem>

website/docs/api/spec.md

@@ -882,7 +882,8 @@ Registered listeners MUST receive:
 
 Registered listeners MAY receive:
 
-*   `traceId` – Correlates related actions and messages.
+*   `traceId` – A unique identifier for tracing the flow of context or intent messages across applications.
+*   `signature` – A cryptographic signature that can be used to verify the authenticity and integrity of the context or intent message.
 *   `custom` – Implementation-specific metadata.
 
 <!-- TODO insert security/signature field names here -->
@@ -892,7 +893,7 @@ Registered listeners MAY receive:
 The Desktop Agent MAY provide a `traceId` to intent handlers.
 
 *   If the originating app provides a `traceId`, the Desktop Agent MUST forward it.
-*   If not, the Desktop Agent MAY generate a UUID.
+*   If no `traceId` is provided by the app, the Desktop Agent MAY generate a new one.
 
 Apps MAY propagate `traceId` when performing actions as a result of another FDC3 action. This supports observability and correlation across workflows.
 
@@ -925,12 +926,20 @@ fdc3.addIntentListener("ViewContact", (contactContext, metadata) => {
 
 ### Timestamp
 
+The `timestamp` indicates when the context was broadcast or the intent was raised.  
+This can be used for debugging, auditing, or ordering events.
+
 The Desktop Agent MUST provide timestamp information.  
 Apps SHOULD NOT provide timestamps; if they do, the Desktop Agent MUST ignore them.
 
 ### Source
 
+The `source` identifies the app instance that originated the context or intent.
+
 The Desktop Agent MUST provide source information in the form of an `AppIdentifier`.  
 Apps SHOULD NOT provide source; if they do, the Desktop Agent MUST ignore it.
 
-<!-- TODO insert security/signature field overviews here -->
+### Signature
+
+The `signature` can be used to verify the authenticity and integrity of a context or intent message.  
+If a signature is provided by an app, it MAY be verified by the Desktop Agent.