Complete "Passing contextual information" pattern documentation

Documents `updateModelContext` for keeping the model informed about user
interactions. The example shows a shopping cart use case with YAML frontmatter
for structured, parseable context.

Also refines the `updateModelContext` JSDoc to clarify the difference from
`sendMessage` and removes the `structuredContent` example.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs/patterns.md

@@ -58,6 +58,12 @@ Listen for display mode changes via {@link app!App.onhostcontextchanged onhostco
 
 {@includeCode ../src/app.examples.ts#App_onhostcontextchanged_respondToDisplayMode}
 
+## Passing contextual information from the App to the Model
+
+Use {@link app!App.updateModelContext updateModelContext} to keep the model informed about what the user is viewing or interacting with. Structure the content with YAML frontmatter for easy parsing:
+
+{@includeCode ../src/app.examples.ts#App_updateModelContext_appState}
+
 ## Persisting widget state
 
 To persist widget state across conversation reloads (e.g., current page in a PDF viewer, camera position in a map), use [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) with a stable identifier provided by the server.

src/app.examples.ts

@@ -345,25 +345,29 @@ function App_sendLog_debugState(app: App) {
 /**
  * Example: Update model context with current app state.
  */
-async function App_updateModelContext_appState(app: App) {
+async function App_updateModelContext_appState(
+  app: App,
+  itemList: string[],
+  totalCost: string,
+  currency: string,
+) {
   //#region App_updateModelContext_appState
+  const markdown = `---
+item-count: ${itemList.length}
+total-cost: ${totalCost}
+currency: ${currency}
+---
+
+User is viewing their shopping cart with ${itemList.length} items selected:
+
+${itemList.map((item) => `- ${item}`).join("\n")}`;
+
   await app.updateModelContext({
-    content: [{ type: "text", text: "User selected 3 items totaling $150.00" }],
+    content: [{ type: "text", text: markdown }],
   });
   //#endregion App_updateModelContext_appState
 }
 
-/**
- * Example: Update with structured content.
- */
-async function App_updateModelContext_structuredContent(app: App) {
-  //#region App_updateModelContext_structuredContent
-  await app.updateModelContext({
-    structuredContent: { selectedItems: 3, total: 150.0, currency: "USD" },
-  });
-  //#endregion App_updateModelContext_structuredContent
-}
-
 /**
  * Example: Report runtime error to model.
  */

src/app.ts

@@ -654,13 +654,12 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
   /**
    * Update the host's model context with app state.
    *
-   * Unlike `sendLog`, which is for debugging/telemetry, context updates
-   * are intended to be available to the model in future reasoning,
-   * without requiring a follow-up action (like `sendMessage`).
+   * Context updates are intended to be available to the model in future
+   * turns, without triggering an immediate model response (unlike {@link sendMessage}).
    *
    * The host will typically defer sending the context to the model until the
-   * next user message (including `ui/message`), and will only send the last
-   * update received. Each call overwrites any previous context update.
+   * next user message — either from the actual user or via `sendMessage`. Only
+   * the last update is sent; each call overwrites any previous context.
    *
    * @param params - Context content and/or structured content
    * @param options - Request options (timeout, etc.)
@@ -671,9 +670,6 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
    * @example Update model context with current app state
    * {@includeCode ./app.examples.ts#App_updateModelContext_appState}
    *
-   * @example Update with structured content
-   * {@includeCode ./app.examples.ts#App_updateModelContext_structuredContent}
-   *
    * @example Report runtime error to model
    * {@includeCode ./app.examples.ts#App_updateModelContext_reportError}
    *