Merge remote-tracking branch 'origin/master' into simpl-c-web-observation

# Conflicts:
#	docs/architecture.md
#	packages/web/web/src/index.ts

packages/web/web/src/index.ts

@@ -110,6 +110,8 @@ export class WebService extends Service {
    * Register a search provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
    * if its id is already registered for search. Returns a disposer; disposed
    * with the calling fiber.
+   * @param provider - the provider; its `id` is the registry key.
+   * @returns the disposer that unregisters the provider.
    */
   registerSearchProvider(provider: WebSearchProvider): () => void {
     return this.registerProvider(this.searchProviders, provider)
@@ -119,6 +121,8 @@ export class WebService extends Service {
    * Register a fetch provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
    * if its id is already registered for fetch. Returns a disposer; disposed
    * with the calling fiber.
+   * @param provider - the provider; its `id` is the registry key.
+   * @returns the disposer that unregisters the provider.
    */
   registerFetchProvider(provider: WebFetchProvider): () => void {
     return this.registerProvider(this.fetchProviders, provider)
@@ -142,6 +146,9 @@ export class WebService extends Service {
    * time with the selection rules above; throws {@link WebError} when the
    * capability cannot run. The seam enforces `request.maxResults` on the result:
    * if the provider over-returns, `sources[]` is truncated and `truncated` set.
+   * @param request - the query plus result-shaping options.
+   * @param exec - the tool-execution context, forwarded to the provider.
+   * @returns the provider's results, capped to `request.maxResults`.
    */
   async search(request: WebSearchRequest, exec?: WebExecContext): Promise<WebSearchResult> {
     const provider = resolveProvider({
@@ -156,6 +163,9 @@ export class WebService extends Service {
    * Retrieve one URL through the selected provider. Resolves the provider at
    * call time with the selection rules above; throws {@link WebError} when the
    * capability cannot run. A non-2xx response is a result, not a throw.
+   * @param request - the URL plus retrieval options.
+   * @param exec - the tool-execution context, forwarded to the provider.
+   * @returns the retrieval outcome; non-2xx responses resolve descriptively.
    */
   async fetch(request: WebFetchRequest, exec?: WebExecContext): Promise<WebFetchResult> {
     const provider = resolveProvider({