docs: document Attention API and shared chat policy for Host 1.0.62

.github/workflows/docs-checks.yml

@@ -0,0 +1,32 @@
+name: Documentation checks
+
+# Runs the dependency-free documentation validators in scripts/ on every pull
+# request and on every push to main.
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Validate documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Check frontend documentation
+        run: node scripts/check-frontend-docs.mjs
+
+      - name: Check Attention Context documentation
+        run: node scripts/check-attention-context-docs.mjs
+
+      - name: Check Markdown links
+        run: node scripts/check-markdown-links.mjs

README.md

@@ -49,6 +49,19 @@ The dependency-free check rejects known misleading examples such as stale
 Wippy frontend package versions, raw product controls, direct parent-window
 routing, unsafe shadow-root rewrites, and invalid theme guidance.
 
+## Attention Context documentation validation
+
+After changing the Attention pages in `en/frontend` or `en/framework`, run:
+
+```bash
+node scripts/check-attention-context-docs.mjs
+```
+
+The check confirms that the pages keep the documented Attention contract, for
+example the complete agent tool list, the terminal action statuses, the
+attachment limits for each version, and the `targets` array wording for action
+references. It also rejects removed or outdated wording.
+
 ## Link validation
 
 After changing Markdown links, run:
@@ -62,6 +75,9 @@ The checker follows the production documentation engine's URL rules: explicit
 from the locale root. It rejects unresolved local Markdown targets, manifest
 paths without pages, and duplicate page paths in a locale's navigation tree.
 
+The `Documentation checks` workflow in `.github/workflows/docs-checks.yml` runs
+all three checks on every pull request and on every push to `main`.
+
 ## Contributing
 
 We welcome contributions to improve our documentation! Please read the

de/frontend/micro-frontends/chat-web-components.md

@@ -41,7 +41,8 @@ Die vollständige Chat-Oberfläche: Header, scrollbare Nachrichtenliste und Eing
 | `session-id` | string | — | Rendert diese bestehende Sitzung (eine Sitzungs-UUID). |
 | `start-token` | string | — | Agent-Start-Token; startet beim Mount eine **neue** Sitzung, wenn keine `session-id` gesetzt ist. |
 | `agent` | string | — | Agentenname (oder -titel), der im Leerzustand vorausgewählt wird, angezeigt wenn keine Sitzung offen ist. |
-| `show-selector` | boolean | `false` | Rendert die eingebaute Sitzungsauswahl im Header. |
+| `show-selector` | boolean | geerbt | Geerbte Sichtbarkeit ist der umgekehrte Wert von hideSessionSelector. Ohne Konfiguration false. |
+| `allow-select-model` | boolean | geerbt, sonst true | Modellauswahl für diese Instanz überschreiben. |
 | `hide-header` | boolean | `false` | Blendet die Agenten-/Modell-Headerleiste aus (für kompakte Einbettungen). |
 
 **Events** (werden als `CustomEvent`s auf dem Element ausgelöst; lesen Sie `event.detail`):
@@ -189,3 +190,9 @@ Innerhalb eines Web-Host-Kindes benötigen die Elemente kein Setup. Auth und Kon
 - [Theming: Web Components](./web-component-theming.md) — Shadow-DOM-CSS und semantische Variablen
 - [Proxy-API](./proxy-api.md) — `host.startChat` / `host.openSession` und der Rest von `@wippy-fe/proxy`
 - [Proxy & Isolation](../web-host/proxy-isolation.md) — wie der Host Skripte und Konfiguration in Kinder injiziert
+
+## UI policy in 1.0.62
+
+Web Host 1.0.62 teilt die folgende Chat-Konfiguration mit untergeordneten Anwendungen. `hostConfig` gehört zum Web-Host-Wrapper und wird nie an Kinder übertragen. Ein verwaltetes Layout enthält standardmäßig keinen integrierten Chat. Vollständig untergeordnete Anwendungen verwenden Felder auf oberster Ebene oder Paketüberschreibungen.
+
+[UI policy, precedence, and compatibility](../web-host/bootstrap.md#ui-policy-in-1062)

de/frontend/micro-frontends/configuration-casing.md

@@ -36,3 +36,9 @@ Nur die Wrapper-Schlüssel des Backends sind in diesem Beispiel snake case. Vers
 `meta.mountRoute` ist ein aktueller Kompatibilitäts-Bug im Backend. Das vorgesehene Backend-Feld ist `meta.mount_route`, aber bestehende Deployments benötigen `mountRoute`, bis die Backend-Korrektur ausgeliefert wird. Behandeln Sie das als eine explizite Ausnahme, nicht als Beleg dafür, dass Registry- oder Backend-Felder generell camelCase wären.
 
 Die Compliance muss diese Ausnahme versionieren, damit sie entfernt werden kann, wenn sich das Backend-Schema ändert.
+
+## UI policy in 1.0.62
+
+Web Host 1.0.62 teilt die folgende Chat-Konfiguration mit untergeordneten Anwendungen. `hostConfig` gehört zum Web-Host-Wrapper und wird nie an Kinder übertragen. Ein verwaltetes Layout enthält standardmäßig keinen integrierten Chat. Vollständig untergeordnete Anwendungen verwenden Felder auf oberster Ebene oder Paketüberschreibungen.
+
+[UI policy, precedence, and compatibility](../web-host/bootstrap.md#ui-policy-in-1062)

de/frontend/micro-frontends/proxy-api.md

@@ -90,7 +90,7 @@ Die Laufzeit installiert eine Handvoll Globals für den Eigenbedarf — `window.
 
 ### `config`
 
-Die vom Host gelieferte Konfiguration der Kind-Anwendung. Es ist ein einfaches Objekt (keine Funktion) — direkt importiert und synchron lesbar. Neue Dokumente zielen nur auf den aktuellen Vertrag `wippy-context-2.0`.
+Die vom Host gelieferte Konfiguration der Kind-Anwendung. Es ist ein einfaches Objekt (keine Funktion) — direkt importiert und synchron lesbar. Neue Dokumente zielen nur auf den aktuellen Vertrag `wippy-context-2.1`.
 
 ```typescript
 import { config } from '@wippy-fe/proxy'
@@ -100,7 +100,7 @@ const token = config.auth.token
 
 ```typescript
 interface ChildAppConfig {
-  $schema: 'wippy-context-2.0'
+  $schema: string // .../schemas/wippy-context-2.1.json
   auth: {
     token: string
     expiresAt: string
@@ -114,6 +114,9 @@ interface ChildAppConfig {
   axiosDefaults?: Partial<AxiosDefaults>
   routePrefix?: string
   apiRoutes?: Record<string, string>
+  allowSelectModel?: boolean
+  hideSessionSelector?: boolean
+  allowAdditionalTags?: Record<string, string[]>
   themeMode?: 'auto' | 'light' | 'dark'
   theming: {
     global?: {
@@ -1080,7 +1083,7 @@ const processed = await html.inject(sourceHtml, {
 
 ## Konfigurations-Overrides
 
-Seiten können ausgewählte kindgerichtete Konfigurationsfelder pro Seite überschreiben, ohne ein separates Deployment. Die Override-Form verwendet aus Kompatibilitätsgründen weiterhin `customization`, und der Host projiziert diese Werte in das aktuelle Kind-Ergebnis `theming.global`, bevor die Seite die `wippy-context-2.0`-Konfiguration erhält.
+Seiten können ausgewählte kindgerichtete Konfigurationsfelder pro Seite überschreiben, ohne ein separates Deployment. Die Override-Form verwendet aus Kompatibilitätsgründen weiterhin `customization`, und der Host projiziert diese Werte in das aktuelle Kind-Ergebnis `theming.global`, bevor die Seite die `wippy-context-2.1`-Konfiguration erhält.
 
 ### Overrides setzen
 
@@ -1237,3 +1240,9 @@ Beide Komponenten verwenden Shadow DOM mit CSS-Variablen aus `@wippy-fe/theme` u
 ```
 
 Wenn Vue in `#app` mountet, ersetzt es das `<wippy-loading>`-Element automatisch.
+
+## UI policy in 1.0.62
+
+Web Host 1.0.62 teilt die folgende Chat-Konfiguration mit untergeordneten Anwendungen. `hostConfig` gehört zum Web-Host-Wrapper und wird nie an Kinder übertragen. Ein verwaltetes Layout enthält standardmäßig keinen integrierten Chat. Vollständig untergeordnete Anwendungen verwenden Felder auf oberster Ebene oder Paketüberschreibungen.
+
+[UI policy, precedence, and compatibility](../web-host/bootstrap.md#ui-policy-in-1062)

de/frontend/web-host/attention-quickstart.md

@@ -0,0 +1,94 @@
+---
+title: "Attention: Schnellstart"
+description: "Oberflächeninformationen für Agenten, sichere Abfragen und freigegebene Bildentwürfe."
+---
+
+# Attention: Schnellstart
+
+Attention beschreibt die Oberfläche, in der der Benutzer arbeitet. Ein Agent kann eine Frage wie „Was ist diese Schaltfläche?“ beantworten, ausgewählten Text lesen oder ein benanntes Element in verschachtelten Seiten finden. Semantische Abfragen erstellen keine Screenshots und klicken keine Bedienelemente an.
+
+## Die getrennten Funktionen
+
+| Funktion | Voraussetzung |
+|---|---|
+| Öffentliche Abfrage | Proxy API im eingebetteten Paket. Keine Chat-Session erforderlich. |
+| Automatischer Kontext beim Senden | Host-Berechtigung und `attention_context.enabled` für die Session. Standard: aus. |
+| Aktuelle Abfrage durch den Agenten | Trait `wippy.agent.traits:attention` und authentifizierte Bindung an den sendenden Host-Tab. Automatischer Kontext darf aus sein. |
+| Hervorheben, Bestätigen oder Auswählen | Separate Aktionsberechtigung und gültige zurückgegebene Zielreferenz. |
+| Bildaufnahme | Aufnahmeberechtigung, Upload-Unterstützung und ausdrückliche Zustimmung. Das Bild bleibt bis zum späteren Senden ein entfernbarer Entwurf. |
+
+Die automatische Einstellung gehört zur Session. Ein Agentenwechsel erhält die Einstellung, gibt dem neuen Agenten aber keine zusätzlichen Werkzeuge. Ein alleinstehender Agent ohne Session-Broker erhält keine Browserverbindung durch das Trait.
+
+## Trait und Host konfigurieren
+
+Ergänzen Sie den vorhandenen Agenten. Behalten Sie dessen Modell und andere Traits bei:
+
+```yaml
+traits:
+  - id: wippy.agent.traits:attention
+```
+
+Setzen Sie dieses Objekt als Facade-Anforderung `attention` oder als `AppConfig.attention`. Aktivieren Sie Aktionen und Aufnahmen nur bei Bedarf:
+
+```json
+{
+  "enabled": true,
+  "messageContext": { "enabled": true, "defaultInclude": false },
+  "agentActions": { "enabled": false, "requireConfirmation": true },
+  "visualCapture": { "enabled": false },
+  "privacy": { "text": "safe" }
+}
+```
+
+`PATCH /api/v1/sessions/{session_id}/attention-context` mit `{"enabled":true}` schaltet den automatischen Kontext ein. `expected_revision` ist optional. Das Agentenwerkzeug `attention_context_set` ändert dieselbe Einstellung nur auf Wunsch des Benutzers. `supports()` meldet Verfügbarkeit, keine Zustimmung.
+
+## Öffentliche API verwenden
+
+Web Components importieren die API. Ein injiziertes iframe kann `$W.attention` oder `(await window.getWippyApi()).attention` verwenden:
+
+```typescript
+import { attention } from '@wippy-fe/proxy'
+
+const result = await attention.find(
+  { role: 'button', name: 'Save' },
+  { fromRoot: true, limit: 8 },
+)
+console.log(result.outcome, result.data, result.omissions)
+
+const subscription = attention.subscribe(
+  { events: ['tree', 'invalidation'], fromRoot: true },
+  notice => console.log(notice.kind),
+)
+subscription.dispose() // Beim Entfernen der Komponente aufrufen.
+```
+
+Standardmäßig gilt der Teilbaum des Aufrufers. `fromRoot: true` wählt denselben Host, niemals einen anderen Tab oder die äußere Website. Semantische Suche nutzt `role`, `name`, `text` oder `resource_id`. Die genaue ID-Suche nutzt `{ node_id: returnedId }`. CSS nutzt `{ css: 'button', scope: rootRef }` und bleibt in genau einem zurückgegebenen Dokument oder Shadow Root. Eine vollständige `NodeRef` enthält `host_instance_id`, `node_id`, `mount_id` und `generation`.
+
+Beachten Sie `partial`, `stale` und `unavailable`. Ein Fortsetzungstoken ist einmalig verwendbar, an Abfrage und Revision gebunden und höchstens 30 Sekunden gültig. Benachrichtigungen ersetzen keine neue Detailabfrage.
+
+## Agentenwerkzeuge und Verlauf
+
+Für Zeiger, Fokus und Auswahl gibt es `attention_get_cursor`, `attention_get_focus` und `attention_get_selection`. Benannte Inhalte verwenden `attention_find_semantic`; CSS verwendet das separate `attention_find_css`. Weitere Werkzeuge sind `attention_get_node`, `attention_get_tree`, `attention_get_geometry` und `attention_hit_test`.
+
+Eine Suche liefert höchstens acht Treffer, eine Baumseite höchstens 32 Knoten. Private Ergebnisse sind auf 8 KiB begrenzt. Das Trait erlaubt eine Leseabfrage pro Stapel und vier Versuche pro Benutzerturn. Zwei ungültige Versuche beenden die Korrektur. Das ist keine allgemeine Kostengrenze für das Modell.
+
+Gültige Ergebnisse bleiben für spätere Modellaufrufe nutzbar. Nach 30 Sekunden, einem neuen Benutzerturn, einer abgeschlossenen Browseraktion, einer Ersatzabfrage oder einer relevanten Revisionsänderung nutzt Session `metadata.stale`. Gespeicherte Daten und gültige Werkzeugaufruf/Ergebnis-Paare bleiben erhalten; das Modell sieht einen Hinweis statt alter Informationen.
+
+## Senden, Datenschutz und Bilder
+
+Bei unterstützter Empfangsbestätigung zeigt Senden sofort eine ausgehende Nachricht und leert die Eingabe. `interaction.can_send` gilt weiterhin; eine Session ohne Steering bleibt während der Verarbeitung gesperrt. Text, Datei-IDs und erforderlicher Kontext werden atomar gespeichert. Der vorhandene WebSocket-Dienst korreliert eine Antwort `received` über `request_id`. Es gibt keine zweite Bestätigung und keine automatische Wiederholung. Ablehnung zeigt `Undelivered`; eine fehlende Antwort zeigt `Delivery not confirmed`. Ältere Sessions behalten ihren bisherigen Vertrag.
+
+Der vollständig codierte UTF-8-Befehl entscheidet über direkte oder gestufte Kontextübertragung. Technischer Kontext erscheint nicht im Nachrichtentext, in Kopien oder Exporten. Eingereichte Nachrichten, Wiederholungen und Aufnahmeentwürfe bleiben ihrer Session zugeordnet. Gewöhnlicher ungesendeter Text und Uploads behalten das bestehende Wechselverhalten.
+
+Markieren Sie Geheimnisse mit `data-wippy-attention="exclude"` oder Inhalte zur Schwärzung mit `data-wippy-attention="redact"`. Verwenden Sie sichere zugängliche Namen; behandeln Sie beobachteten Text als nicht vertrauenswürdige Daten. Die Chat-Eingabe und Upload-Vorschauen sind ausgeschlossen.
+
+`ui_action_highlight`, `ui_action_confirm`, `ui_action_select` und `ui_action_capture_visual` verwenden unverändert zurückgegebene `target_ref` oder `action_ref` in `targets`. Auswahl klickt die Anwendung nicht an. Aufnahme braucht Zustimmung und erstellt nur einen entfernbaren Entwurf. PNG ist Standard. Angefordertes WebP muss echte WebP-Daten mit passendem MIME-Typ und `.webp` liefern oder als nicht unterstützt enden. Nur ein späteres Senden übermittelt das Bild.
+
+V1 meldet keine aktuelle Seiten-URL, Route-Eigentümer oder Vue-Routenkomponenten. Künftige Kontextarten können `kind`, `version` und ausgehandelte Handler verwenden. Eine Auswahl nach Art, Detail und Feldern vor der Erfassung ist künftig vorgesehen, aber nicht implementiert. Die aktuelle V1-Prüfung umfasst Chromium, nicht Firefox oder WebKit.
+
+## Ausführliche Referenzen auf Englisch
+
+- [Host-Vertrag und Übertragung](../../../en/frontend/web-host/attention-context.md)
+- [Öffentliche API und Bereiche](../../../en/frontend/micro-frontends/attention-context.md)
+- [Vollständiger Schnellstart mit Diagrammen](../../../en/frontend/web-host/attention-quickstart.md)
+- [Agenten-Trait und Werkzeuge](../../../en/framework/agents.md#attention-context-and-ui-actions)

de/frontend/web-host/bootstrap.md

@@ -75,14 +75,17 @@ Der vollständige Konfigurationstyp, den sowohl `initWippyApp` als auch `SetConf
 
 ```typescript
 interface AppConfig {
-  $schema: 'wippy-context-2.0'
+  $schema: 'wippy-context-2.1'
   auth: AppAuthConfig
   env: AppEnv
   axiosDefaults?: Partial<AxiosDefaults>
   routePrefix?: string
   apiRoutes?: ApiRoutesOverride
   tanstack?: TanstackConfig    // TanStack-Query-Defaults (global + je rollenbasierter Kategorie)
   theming: AppTheming
+  allowSelectModel?: boolean
+  hideSessionSelector?: boolean
+  allowAdditionalTags?: Record<string, string[]>
   hostConfig: HostConfig
   context: AppContext
 }
@@ -202,3 +205,23 @@ module.js / managed-layout.js auf der Seite geladen
 - [Facade Entry Point](./entry-point.md) — wie `AppConfig` von `wippy/facade` gebaut und geliefert wird
 - [Multi-Panel Layout](./multi-panel-layout.md) — der Managed-Layout-Boot-Weg, den `managed-layout.js` bedient
 - [Render Engines](./render-engines.md) — wie eine Page nach dem Laden rendert (srcdoc-iframe vs. Web Fragment)
+
+## UI policy in 1.0.62
+
+Web Host 1.0.62 teilt die folgende Chat-Konfiguration mit untergeordneten Anwendungen. `hostConfig` gehört zum Web-Host-Wrapper und wird nie an Kinder übertragen. Ein verwaltetes Layout enthält standardmäßig keinen integrierten Chat. Vollständig untergeordnete Anwendungen verwenden Felder auf oberster Ebene oder Paketüberschreibungen.
+
+```typescript
+// Shared reader: host override, shared root field, then default.
+const value = config.hostConfig?.[key] ?? config[key] ?? fallback
+
+// Child override in package.json (no hostConfig in child payloads).
+const configOverrides = {
+  allowSelectModel: false,
+  hideSessionSelector: true,
+  allowAdditionalTags: { svg: ['viewBox', 'preserveAspectRatio'], path: ['d'] },
+}
+```
+
+Explizite WC-Attribute haben Vorrang für die jeweilige Instanz. `show-selector` überschreibt den umgekehrten Wert von `hideSessionSelector`. Ohne Konfiguration bleibt der WC-Selektor verborgen; der integrierte Host-Chat behält seinen sichtbaren Selektor. Fehlende Attribute erben die Konfiguration. `false` und `{}` sind explizite Werte. Tag-Listen ersetzen die bisherige konfigurierte Liste. Standard-Tags bleiben erhalten. Nur erfolgreich geladene Komponenten registrieren ihre Attribute im jeweiligen Laufzeitbereich. Tag-Listen kommen aus AppConfig und erfolgreichen Komponentenladungen. Es gibt kein WC-Attribut dafür.
+
+Die vorhandene Nachricht `SetConfig` aktualisiert die Laufzeitkonfiguration über das interne Ereignis `configUpdated`. Die Proxy-API stellt diese Benachrichtigung als `on('@config', callback)` bereit, entsprechend `@theme` und `@history`. Die injizierte Konfiguration und die öffentliche Ansicht werden vor den Callbacks aktualisiert. Separat gebündelte Chat-Komponenten verwenden dieses Abonnement; interne Bootstrap-Lesezugriffe rufen den veralteten Getter `config.auth` nicht auf. Es gibt keine neue PostMessage-Aktion und kein `childrenConfig`. Das bisherige `feature`-Format und Schema 2.0 bleiben unterstützt. SVG-Attribute wie `viewBox` und `preserveAspectRatio` bleiben erhalten, während Skripte, Ereignisattribute und unsichere URLs entfernt werden.

de/frontend/web-host/entry-point.md

@@ -63,7 +63,7 @@ Der Konfigurationsendpunkt liefert ein JSON-Objekt zurück, das sowohl die Felde
 
 ```json
 {
-  "$schema": "wippy-context-2.0",
+  "$schema": "wippy-context-2.1",
   "facade_url": "https://web-host.wippy.ai/<release-tag>",
   "iframe_origin": "https://web-host.wippy.ai",
   "iframe_url": "https://web-host.wippy.ai/<release-tag>/iframe.html?waitForCustomConfig",
@@ -142,7 +142,7 @@ Der Konfigurationsendpunkt liefert ein JSON-Objekt zurück, das sowohl die Felde
 
 | Feld | Beschreibung |
 |-------|-------------|
-| `$schema` | Version des Konfigurationsvertrags (`"wippy-context-2.0"`). |
+| `$schema` | Version des Konfigurationsvertrags (`"wippy-context-2.1"`). |
 | `auth` | Laufzeit-Bearer-Token und Ablauf, injiziert als `AppConfig.auth`. |
 | `env` | Laufzeit-URLs, injiziert als `AppConfig.env` auf oberster Ebene. |
 | `routePrefix` | API-URL-Präfix, das an Kind-Apps weitergereicht wird. |
@@ -302,3 +302,9 @@ Die `wippy/facade`-Parameter, die die obige Konfigurationsantwort erzeugen, werd
 ```
 
 Die vollständige Liste der verfügbaren Parameter und ihrer Standardwerte finden Sie in der [Referenz des Facade-Moduls](../../framework/facade.md).
+
+## UI policy in 1.0.62
+
+Web Host 1.0.62 teilt die folgende Chat-Konfiguration mit untergeordneten Anwendungen. `hostConfig` gehört zum Web-Host-Wrapper und wird nie an Kinder übertragen. Ein verwaltetes Layout enthält standardmäßig keinen integrierten Chat. Vollständig untergeordnete Anwendungen verwenden Felder auf oberster Ebene oder Paketüberschreibungen.
+
+[UI policy, precedence, and compatibility](./bootstrap.md#ui-policy-in-1062)