docs: add widget YAML config and /communities endpoint

neuromechanist · neuromechanist · commit 3049770867a1 · 2026-02-07T10:52:03.000-08:00
- Schema reference: add widget section (title, initial_message, placeholder, suggested_questions)
- Widget deployment: document two-layer config (YAML defaults + JS overrides), add widgetInstructions
- Quick start: add widget to example config.yaml, simplify widget deploy step
- API reference: add GET /communities endpoint
diff --git a/docs/osa/api-reference.md b/docs/osa/api-reference.md
@@ -62,6 +62,37 @@ Response:
 }
 ```
 
+### List Communities
+
+Get all available communities and their widget configuration.
+
+```
+GET /communities
+```
+
+Response:
+```json
+[
+  {
+    "id": "hed",
+    "name": "HED (Hierarchical Event Descriptors)",
+    "description": "Event annotation standard for neuroimaging research",
+    "status": "available",
+    "widget": {
+      "title": "HED Assistant",
+      "initial_message": "Hi! I'm the HED Assistant...",
+      "placeholder": "Ask about HED...",
+      "suggested_questions": [
+        "What is HED and how is it used?",
+        "How do I annotate an event with HED tags?"
+      ]
+    }
+  }
+]
+```
+
+This endpoint is public (no authentication required) and is used by the widget to load display configuration from the community YAML configs.
+
 ### Chat
 
 Send a message and receive a streaming response.
diff --git a/docs/osa/deployment/widget.md b/docs/osa/deployment/widget.md
@@ -17,15 +17,33 @@ Add two script tags to your HTML:
 
 The widget appears as a chat bubble in the bottom-right corner of the page.
 
+## How Configuration Works
+
+Widget configuration uses a two-layer approach:
+
+1. **YAML defaults** (community-level): Title, greeting, placeholder, and suggested questions are defined in each community's `config.yaml` under the `widget` section. These are served by the `GET /communities` API endpoint.
+2. **JavaScript overrides** (page-level): Embedders can override any field via `setConfig()`. Any value set in JavaScript takes precedence over the YAML defaults.
+
+This means most embedders only need to set `communityId`; the widget fetches its display configuration from the API automatically.
+
 ## Configuration Options
 
+### Display Options (from YAML defaults)
+
+These fields are typically configured in the community's `config.yaml` and loaded automatically. You can override them per-page via `setConfig()`:
+
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `communityId` | string | `'hed'` | Which community assistant to use |
-| `title` | string | `'HED Assistant'` | Widget header title |
-| `initialMessage` | string | HED greeting | First message shown to user |
-| `placeholder` | string | `'Ask about HED...'` | Input placeholder text |
-| `suggestedQuestions` | string[] | HED questions | Clickable suggestion buttons |
+| `title` | string | From YAML or community name | Widget header title |
+| `initialMessage` | string | From YAML | First message shown to user |
+| `placeholder` | string | From YAML or `'Ask a question...'` | Input placeholder text |
+| `suggestedQuestions` | string[] | From YAML | Clickable suggestion buttons |
+
+### Behavior Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
 | `apiEndpoint` | string | Auto-detected | Backend API URL |
 | `storageKey` | string | Auto-derived | localStorage key for chat history |
 | `turnstileSiteKey` | string | `null` | Cloudflare Turnstile site key |
@@ -37,10 +55,11 @@ The widget appears as a chat bubble in the bottom-right corner of the page.
 | `pageContextStorageKey` | string | `'osa-page-context-enabled'` | localStorage key for page context preference |
 | `pageContextLabel` | string | `'Share page URL...'` | Label text for the page context checkbox |
 | `fullscreen` | boolean | `false` | Open chat in fullscreen mode |
+| `widgetInstructions` | string | `null` | Per-page context hint sent to the assistant (max 2000 chars) |
 
 ### Minimal Configuration
 
-Only `communityId` is required. Everything else has sensible defaults:
+Only `communityId` is required. The widget fetches display settings (title, greeting, placeholder, suggested questions) from the `/communities` API automatically:
 
 ```html
 <script src="https://osa-demo.pages.dev/osa-chat-widget.js"></script>
@@ -51,6 +70,22 @@ Only `communityId` is required. Everything else has sensible defaults:
 </script>
 ```
 
+### Per-Page Customization
+
+Use `widgetInstructions` to give the assistant context about the specific page where the widget is embedded. This is sent to the backend as part of the page context and helps the assistant provide more relevant answers:
+
+```html
+<script src="https://osa-demo.pages.dev/osa-chat-widget.js"></script>
+<script>
+  OSAChatWidget.setConfig({
+    communityId: 'hed',
+    widgetInstructions: 'The user is on the HED online validation tools page. Focus on helping with validation errors and tool usage.'
+  });
+</script>
+```
+
+This is useful when the same community assistant is embedded across multiple pages (e.g., documentation, tools, tutorials) and you want the assistant to adapt its responses to the page context.
+
 ### Full Configuration
 
 ```html
@@ -67,6 +102,7 @@ Only `communityId` is required. Everything else has sensible defaults:
       'Validate my HED string',
       'What tools are available?'
     ],
+    widgetInstructions: 'User is on the annotation guide page.',
     showExperimentalBadge: false,
     allowPageContext: true,
     pageContextDefaultEnabled: true
@@ -142,26 +178,30 @@ When configured, users must complete a Turnstile challenge before sending messag
 
 ## API Endpoints
 
-The widget communicates with two backend endpoints:
+The widget communicates with the following backend endpoints:
 
 | Endpoint | Method | Description |
 |----------|--------|-------------|
+| `/communities` | GET | Fetch available communities and widget config |
 | `/{communityId}/ask` | POST | Send a question, get a response |
 | `/health` | GET | Check backend status |
 
+On load, the widget fetches `/communities` to get display configuration (title, greeting, placeholder, suggested questions) for all available communities. This eliminates the need to hardcode these values in JavaScript.
+
 ### Request Format
 
 ```json
 {
   "question": "What is HED?",
   "page_context": {
     "url": "https://hedtags.org/docs/getting-started",
-    "title": "Getting Started - HED"
+    "title": "Getting Started - HED",
+    "widget_instructions": "User is on the getting started page."
   }
 }
 ```
 
-The `cf_turnstile_response` field is also sent by the widget when Turnstile is configured, but this is consumed by the Cloudflare Worker proxy, not the backend API.
+The `widget_instructions` field is optional and only sent when configured via `setConfig({ widgetInstructions: '...' })`. The `cf_turnstile_response` field is also sent by the widget when Turnstile is configured, but this is consumed by the Cloudflare Worker proxy, not the backend API.
 
 ### Response Format
 
@@ -193,14 +233,12 @@ To host the widget yourself:
 
 ## Demo Page
 
-The demo page at [osa-demo.pages.dev](https://osa-demo.pages.dev) showcases all available community assistants with URL-based routing:
+The demo page at [osa-demo.pages.dev](https://osa-demo.pages.dev) dynamically loads all available communities from the `/communities` API and showcases them with URL-based routing:
 
-- `/` - Landing page with community cards
-- `/hed` - HED assistant demo
-- `/bids` - BIDS assistant demo
-- `/eeglab` - EEGLAB assistant demo
+- `/` - Landing page with community cards (populated from API)
+- `/{communityId}` - Community-specific assistant demo (e.g., `/hed`, `/bids`, `/eeglab`)
 
-Each community page auto-configures the widget with the appropriate settings.
+Each community page auto-configures the widget using the YAML-defined defaults. New communities added to the registry appear on the demo page automatically without frontend changes.
 
 ## Troubleshooting
 
diff --git a/docs/osa/registry/quick-start.md b/docs/osa/registry/quick-start.md
@@ -67,6 +67,16 @@ github:
     - org/my-tool
     - org/my-tool-plugins
 
+# Widget display configuration (optional)
+widget:
+  title: My Tool Assistant
+  initial_message: "Hi! I can help with My Tool. What would you like to know?"
+  placeholder: Ask about My Tool...
+  suggested_questions:
+    - How do I get started with My Tool?
+    - What are the configuration options?
+    - How do I use the API?
+
 # Paper search and citation tracking
 citations:
   queries:
@@ -129,26 +139,29 @@ uv run osa sync all --community my-tool
 
 ## Step 6: Deploy the Widget (Optional)
 
-Add the chat widget to your community's website:
+Add the chat widget to your community's website. If you configured the `widget` section in your `config.yaml`, only `communityId` is needed; the widget fetches display settings from the API automatically:
 
 ```html
 <script src="https://osa-demo.pages.dev/osa-chat-widget.js"></script>
+<script>
+  OSAChatWidget.setConfig({
+    communityId: 'my-tool'
+  });
+</script>
+```
+
+You can optionally add per-page context to help the assistant understand the current page:
+
+```html
 <script>
   OSAChatWidget.setConfig({
     communityId: 'my-tool',
-    title: 'My Tool Assistant',
-    initialMessage: 'Hi! I can help with My Tool. What would you like to know?',
-    placeholder: 'Ask about My Tool...',
-    suggestedQuestions: [
-      'How do I get started?',
-      'What are the configuration options?',
-      'How do I use the API?'
-    ]
+    widgetInstructions: 'The user is on the installation guide page.'
   });
 </script>
 ```
 
-See the [Widget Deployment Guide](../deployment/widget.md) for more options.
+See the [Widget Deployment Guide](../deployment/widget.md) for all configuration options.
 
 ## What You Get
 
diff --git a/docs/osa/registry/schema-reference.md b/docs/osa/registry/schema-reference.md
@@ -16,6 +16,7 @@ Complete reference for the community `config.yaml` file format.
 | `github` | object | No | `null` | GitHub sync configuration |
 | `citations` | object | No | `null` | Paper/citation search config |
 | `discourse` | list | No | `[]` | Discourse forum configs |
+| `widget` | object | No | `null` | Widget display configuration (title, greeting, suggestions) |
 | `extensions` | object | No | `null` | Extension points (plugins, MCP) |
 
 ## `id`
@@ -205,6 +206,33 @@ extensions:
       url: https://mcp.my-tool.org
 ```
 
+## `widget`
+
+Widget display configuration for the embedded chat widget. These values provide defaults that the widget loads from the `/communities` API endpoint, so embedders only need to set `communityId` in their JavaScript.
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `title` | string | No | Community `name` | Widget header title (max 100 chars) |
+| `initial_message` | string | No | `null` | Greeting message shown when chat opens (max 1000 chars) |
+| `placeholder` | string | No | `"Ask a question..."` | Input field placeholder text (max 200 chars) |
+| `suggested_questions` | list[string] | No | `[]` | Clickable suggestion buttons (max 10) |
+
+```yaml
+widget:
+  title: HED Assistant
+  initial_message: "Hi! I'm the HED Assistant. I can help with HED annotation, validation, and related tools."
+  placeholder: Ask about HED...
+  suggested_questions:
+    - What is HED and how is it used?
+    - How do I annotate an event with HED tags?
+    - What tools are available for working with HED?
+    - Explain this HED validation error.
+```
+
+When the widget is embedded on a page, it fetches community defaults from `GET /communities` and applies them automatically. Embedders can still override any field via `setConfig()` in JavaScript; see the [Widget Deployment Guide](../deployment/widget.md).
+
+If `widget` is omitted, the widget falls back to generic defaults (title = community name, placeholder = "Ask a question...").
+
 ## `enable_page_context`
 
 When `true` (default), the assistant includes a `fetch_current_page` tool that retrieves content from the web page where the widget is embedded. This allows the assistant to provide contextually relevant answers based on what the user is currently reading.
@@ -254,6 +282,14 @@ citations:
   dois:
     - "10.1016/j.neuroimage.2021.118766"
 
+widget:
+  title: HED Assistant
+  initial_message: "Hi! I'm the HED Assistant. I can help with HED annotations."
+  placeholder: Ask about HED...
+  suggested_questions:
+    - What is HED and how is it used?
+    - How do I annotate an event with HED tags?
+
 discourse:
   - url: https://neurostars.org
     tags:
