docs: document global provider policy and extension registration rejection

.changeset/global-provider-policy.md

@@ -0,0 +1,5 @@
+---
+"@jmfederico/pi-web": patch
+---
+
+Support only globally configured providers (Pi built-ins, environment credentials, and the agent directory's `models.json`). Provider registrations from Pi extensions (`pi.registerProvider`) are now ignored and reported with a session warning instead of leaking into every concurrent session; all other extension features keep working. Configure such providers globally in the agent directory's `models.json` to use them. Session daemon code changed: after updating, restart `pi-web-sessiond.service` manually (`systemctl --user restart pi-web-sessiond`).

docs/plugins.html

@@ -162,6 +162,13 @@
                 prompt files as supported by Pi. Reload the browser page separately for newly discovered or changed
                 PI WEB browser plugins. A routine session daemon restart is not required.
               </p>
+              <p>
+                One exception applies to Pi package extensions: PI WEB supports only globally configured providers
+                (Pi built-ins, environment credentials, and the agent directory's <code>models.json</code>). If an
+                extension calls <code>pi.registerProvider</code>, PI WEB ignores the registration and warns in the
+                session; everything else the extension registers keeps working. Configure such providers globally in
+                the agent directory's <code>models.json</code> instead.
+              </p>
             </section>
 
             <section id="ask-ai">

docs/plugins.md

@@ -25,6 +25,12 @@ When machine federation is enabled, **Settings → Pi packages** targets the cur
 
 Use **Settings → PI WEB plugins** to enable or disable discovered PI WEB browser plugins before the browser imports them. In a federated setup, this plugin enablement surface targets the currently selected machine and labels where changes are saved. If an older or unavailable remote PI WEB server does not advertise selected-machine settings support, PI WEB reports the plugin settings as unsupported or unavailable instead of silently falling back to the gateway. After installing, removing, or updating a Pi package, type `/reload` in each idle PI WEB session on the target machine to refresh Pi runtime resources such as extensions, skills, prompt templates, themes, and context/system prompt files as supported by Pi. Reload the browser page separately for newly discovered or changed PI WEB browser plugins. A routine session daemon restart is not required.
 
+## Extension provider registrations
+
+PI WEB only supports globally configured providers: Pi built-ins, environment credentials, and providers declared in the agent directory's `models.json` (the directory selected by `agent.dir`; see [Configuration](https://pi-web.dev/config)). All sessions share one daemon-wide provider set, so extensions cannot add their own: if a Pi extension calls `pi.registerProvider(...)`, PI WEB ignores the registration and shows a warning in the session naming the provider. The extension itself still loads and everything else it registers keeps working; only the ignored provider's models never appear, so an extension that requires its own provider may load but remain unusable.
+
+To use such a provider, configure it globally in the agent directory's `models.json` instead. Project-level `models.json` files do not add providers to PI WEB sessions.
+
 ## Trust model
 
 Plugins run as JavaScript in the browser app. Treat them as trusted code: