Add developer docs for execution context (elastic#253690)

## Summary
- Add concise developer docs for Core execution context (browser +
server), with usage examples and internal implementation notes.

## Related
Addresses elastic#242415.

Note: This PR does not close the issue yet because the remaining
public/customer documentation lives in a different repository. Will
close the issue when update that.

## Test plan
- Docs-only change.

Made with [Cursor](https://cursor.com)

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: jesuswr

src/core/packages/execution-context/browser-internal/README.md

@@ -1,3 +1,9 @@
 # @kbn/core-execution-context-browser-internal
 
 This package contains the internal types and implementation for Core's browser-side execution context service.
+
+## Pointers
+
+- `x-kbn-context` is attached to `core.http.fetch(...)` requests in `src/core/packages/http/browser-internal/src/fetch.ts`.
+- The header value is URI-encoded JSON produced by `src/core/packages/execution-context/browser-internal/src/execution_context_container.ts`.
+- `HttpFetchOptions.context` is merged with the current global context via `executionContext.withGlobalContext(...)` before serialization.

src/core/packages/execution-context/browser/README.md

@@ -1,3 +1,67 @@
 # @kbn/core-execution-context-browser
 
-This package contains the public types for Core's browser-side execution context service.
+Browser-side execution context helps Kibana associate **HTTP requests** with a meaningful “where did this come from?” context (app/page/entity). Core includes this context in the `x-kbn-context` header on `core.http.fetch(...)` requests so the server can propagate it (for example into Elasticsearch `x-opaque-id` for slow log tracing).
+
+This package contains the **public contract types** for `core.executionContext` in the browser. The common data shape is `KibanaExecutionContext` from [`@kbn/core-execution-context-common`](../common).
+
+## How to set it (recommended)
+
+Use the `useExecutionContext` hook from `@kbn/kibana-react-plugin/public` in your React components.
+
+```ts
+import type { KibanaExecutionContext } from '@kbn/core-execution-context-common';
+import { useExecutionContext } from '@kbn/kibana-react-plugin/public';
+
+const ctx: KibanaExecutionContext = {
+  type: 'application',
+  name: 'discover',
+  page: 'sessionView',
+  id: discoverSessionId,
+};
+
+useExecutionContext(core.executionContext, ctx);
+```
+
+Notes:
+- `page` should be a **stable logical unit** (don’t embed ids in `page`; use `id` for identifiers).
+- The hook clears on unmount; Core also clears the context when the current app changes.
+
+## Nested context with `child` (embeddables/components)
+
+If you already have a parent context (e.g. from an app), add a child context for a nested component:
+
+```ts
+import type { KibanaExecutionContext } from '@kbn/core-execution-context-common';
+
+const parent: KibanaExecutionContext = {
+  type: 'application',
+  name: 'dashboard',
+  page: 'view',
+  id: dashboardId,
+};
+
+const ctx: KibanaExecutionContext = {
+  ...parent,
+  child: { type: 'visualization', name: embeddableType, id: embeddableId },
+};
+```
+
+This pattern is used in e.g. ML embeddables: [`use_embeddable_execution_context.ts`](../../../../../x-pack/platform/plugins/shared/ml/public/embeddables/common/use_embeddable_execution_context.ts).
+
+## Per-request context (for a single `http.fetch`)
+
+You can attach a per-request context that will be merged with the current global context:
+
+```ts
+await core.http.fetch('/api/my_plugin/do_something', {
+  context: { type: 'myPlugin', name: 'doSomething', id: entityId },
+});
+```
+
+## Space id (`space`)
+
+`KibanaExecutionContext.space` is the active space id. In the browser, the Spaces plugin keeps it in sync by calling `core.executionContext.set({ space })`, so most plugins shouldn’t need to set it themselves.
+
+## Keep it small
+
+The `x-kbn-context` header is URI-encoded JSON and is size-limited. Keep context values small and avoid sensitive data (especially in `description` and `meta`).

src/core/packages/execution-context/common/README.md

@@ -1,3 +1,17 @@
 # @kbn/core-execution-context-common
 
 This package contains the common types for Core's execution context.
+
+## `KibanaExecutionContext` (field reference)
+
+`KibanaExecutionContext` is a small object describing where work originates. It is used by the browser to populate the `x-kbn-context` header, and by the server to enrich Elasticsearch `x-opaque-id`.
+
+- **`type`**: high-level category (e.g. `application`, `dashboard`, `visualization`, `task`).
+- **`name`**: public name of an app/feature/subsystem (e.g. `discover`, `lens`, `taskManager`).
+- **`space`**: current space id (when applicable).
+- **`page`**: stable logical unit like a page/tab/route segment (avoid embedding ids; put those in `id`).
+- **`id`**: identifier for the current entity (dashboard id, rule id, saved object id, etc.).
+- **`description`**: human-readable description (avoid large values and sensitive data).
+- **`url`**: browser URL or server endpoint/task URL (avoid unique identifiers if not needed).
+- **`meta`**: optional extra structured details (keep small; avoid sensitive data).
+- **`child`**: nested context spawned from the current one (embeddables/sub-operations); can be chained.

src/core/packages/execution-context/server-internal/README.md

@@ -2,3 +2,9 @@
 
 This package contains the internal types and implementation for Core's server-side execution context service.
 
+## Pointers
+
+- Core HTTP installs request execution context from the `x-kbn-context` header in `src/core/packages/http/server-internal/src/http_server.ts`.
+- `AsyncLocalStorage` storage and the `withContext(...)` implementation live in `src/core/packages/execution-context/server-internal/src/execution_context_service.ts`.
+- `x-kbn-context` parsing and the compact context string used for Elasticsearch `x-opaque-id` live in `src/core/packages/execution-context/server-internal/src/execution_context_container.ts`.
+- Config: `execution_context.enabled` in `src/core/packages/execution-context/server-internal/src/execution_context_config.ts`.

src/core/packages/execution-context/server/README.md

@@ -1,4 +1,43 @@
 # @kbn/core-execution-context-server
 
-This package contains the public types for Core's server-side execution context service.
+Server-side execution context helps Kibana correlate **server work** with a meaningful “origin” (app/page/entity/background task). Core uses it to enrich Elasticsearch `x-opaque-id`, which is useful for tracing expensive searches in Elasticsearch slow logs.
 
+This package contains the **public contract types** for `core.executionContext` on the server. The common data shape is `KibanaExecutionContext` from [`@kbn/core-execution-context-common`](../common).
+
+## Request handling (typical case)
+
+For HTTP requests initiated from the browser, Core’s HTTP layer parses the incoming `x-kbn-context` header and installs it into request-scoped async context. In a normal route handler you generally **do not need to do anything**—Elasticsearch client calls will automatically include the derived `x-opaque-id`.
+
+For more context on how `x-opaque-id` is used to trace slow searches, see Elastic docs: [`Trace an Elasticsearch query in Kibana`](https://www.elastic.co/docs/troubleshoot/kibana/trace-elasticsearch-query-to-the-origin-in-kibana).
+
+## Background/server-only work (use `withContext`)
+
+For work that doesn’t originate from an incoming browser request (task manager, background sync, scheduled jobs, etc.), wrap your work with `core.executionContext.withContext(...)`:
+
+```ts
+import type { KibanaExecutionContext } from '@kbn/core-execution-context-common';
+
+const ctx: KibanaExecutionContext = {
+  type: 'task',
+  name: 'myPlugin',
+  id: taskId,
+  page: 'run',
+  description: 'sync something',
+};
+
+return core.executionContext.withContext(ctx, async () => {
+  // Any Elasticsearch calls made from here will include the derived x-opaque-id
+  await esClient.asInternalUser.ping();
+});
+```
+
+## Debugging
+
+To see stored execution context in Kibana logs, enable debug logging for the `execution_context` logger:
+
+```yml
+logging:
+  loggers:
+    - name: execution_context
+      level: debug
+```