adding agent definitions for analystxp applications

src/platform/plugins/shared/dashboard/AGENTS.md

@@ -0,0 +1,40 @@
+---
+title: Dashboard Plugin Guide for Agents
+---
+
+# Dashboard (dashboard)
+
+The dashboard plugin registers the dashboard app and the dashboard embeddable used across Kibana.
+
+## Architecture and entry points
+- Public plugin: `public/plugin.tsx`
+- Server plugin: `server/plugin.ts`
+- App router: `public/dashboard_app/`
+- Renderer: `public/dashboard_renderer/`
+- State API: `public/dashboard_api/`
+- Saved object logic: `server/dashboard_saved_object/`
+
+## Key concepts
+- Dashboards are saved objects with panels, controls, and query state.
+- Embeddables are the primary mechanism for rendering panels.
+- Dashboard API is the recommended integration surface for reading and rendering.
+
+## Constraints and caveats
+- Server `getDashboard()` and `scanDashboards()` are deprecated; use `client.read`.
+- Locator server limitations: avoid `preserveSavedFilters` in server `getLocation()`.
+- Migration logic is complex; validate panel references when modifying schema.
+
+## Testing
+- Unit tests: `src/platform/plugins/shared/dashboard/jest.config.js`
+- Functional tests: `src/platform/test/functional/apps/dashboard/`
+- X-pack functional: `x-pack/platform/test/functional/apps/dashboard/`
+- API integration: `src/platform/test/api_integration/apis/dashboards/`
+- Example: `yarn test:jest src/platform/plugins/shared/dashboard`
+- If a verifier sub-agent exists (e.g., `kibana-verifier` or `verifier`), run it and include its findings in the test notes.
+
+## Escalation
+If changes impact embeddable contracts or dashboard saved object behavior, coordinate with the owning teams before finalizing.
+
+## References
+- `src/platform/plugins/shared/dashboard/README.asciidoc`
+- `src/platform/test/functional/apps/dashboard/README.md`

src/platform/plugins/shared/discover/AGENTS.md

@@ -0,0 +1,93 @@
+---
+title: Discover Application Guide for Agents
+---
+
+# Discover Application Guide
+
+This document captures practical guidance for working in the Discover plugin. It is optimized for agent-driven development and code review.
+
+## Scope and goals
+
+Discover is the core data exploration app in Kibana and includes the saved search embeddable. Changes here must preserve data correctness, query/state behavior, and consistent user experience across solutions.
+
+## Key concepts
+
+### 1) Discover context awareness (profiles)
+Discover adapts UI and behavior based on context via composable profiles:
+- **Root context** (solution)
+- **Data source context** (ES|QL query or data view)
+- **Document context** (per-row record)
+
+Profiles implement extension points (cell renderers, doc viewer, app menu, etc.) and are composed in order. Start here:
+- Extension point definitions: `public/context_awareness/types.ts`
+- Inventory of extension points: `public/context_awareness/EXTENSION_POINTS_INVENTORY.md`
+- Architecture overview: `public/context_awareness/README.md`
+
+### 2) Plugin structure and entry points
+- Plugin manifest: `kibana.jsonc`
+- Plugin setup/start: `public/plugin.tsx`
+- App routes: `public/application/*`
+  - `public/application/main` for the primary Discover table
+  - `public/application/context` for surrounding documents
+  - `public/application/doc` for single document view
+- Shared UI: `public/components`, `public/hooks`, `public/utils`
+- Embeddable: `public/embeddable`
+- Shared code: `common/`
+- Server-side: `server/`
+
+## Change guidance
+
+### Feature flags
+Discover feature flags are defined in `public/constants.ts`. Use `discover.experimental.enabledProfiles` to enable experimental profiles via `kibana.yml`.
+
+### Profiles and providers
+Profile providers live in `public/context_awareness/profile_providers`. Register providers in:
+- `public/context_awareness/profile_providers/register_profile_providers.ts`
+
+Prefer dedicated provider folders per solution (e.g. `security`) and keep providers focused to a specific context level.
+
+### Dependency constraints
+Discover is a shared plugin and cannot depend directly on solution plugins. If you need solution-owned logic, prefer:
+- Local implementations inside Discover with shared ownership
+- Dedicated shared packages
+- `discover_shared` plugin as a last-resort IoC bridge
+
+## Testing and verification
+
+### Unit tests (Jest)
+Co-locate with code under `public/` and `common/`.
+Example:
+- `yarn test:jest src/platform/plugins/shared/discover`
+
+### Functional tests (FTR)
+Primary Discover suites:
+- `src/platform/test/functional/apps/discover/context_awareness`
+- `src/platform/test/functional/apps/discover/esql`
+Example:
+- `node scripts/functional_test_runner --config src/platform/test/functional/apps/discover/esql/config.ts`
+
+Serverless suites:
+- `x-pack/solutions/observability/test/serverless/functional/test_suites/discover/context_awareness`
+- `x-pack/platform/test/serverless/functional/test_suites/discover`
+
+### E2E tests
+For new end-to-end tests, prefer Scout/Playwright over FTR.
+
+### Verifier
+If a verifier sub-agent exists (e.g., `kibana-verifier` or `verifier`), run it and include its findings in the review/test notes.
+
+## Escalation
+If changes require cross-plugin behavior or ownership changes, coordinate with the owning team(s) for those plugins before finalizing.
+
+## Review checklist (Discover-specific)
+
+- ES|QL query state and URL syncing are preserved
+- Profile resolution still matches expected data sources
+- Extension points compose correctly (no regressions in merged accessors)
+- Default columns, chart sections, and doc viewer tabs behave per workflow docs
+- FTR and serverless suites were considered for user-facing changes
+
+## References
+
+- Discover plugin README: `src/platform/plugins/shared/discover/README.md`
+- Context awareness overview: `src/platform/plugins/shared/discover/public/context_awareness/README.md`

src/platform/plugins/shared/discover_shared/AGENTS.md

@@ -0,0 +1,47 @@
+---
+title: Discover Shared Guide for Agents
+---
+
+# Discover Shared (discoverShared)
+
+This plugin is a **stateful IoC bridge** used to register shared features that Discover can consume **without creating direct plugin dependencies**. Use it sparingly.
+
+## When to use
+- You cannot directly import a solution plugin without creating dependency cycles.
+- The feature is owned by another solution team and cannot be moved into Discover.
+- You have a plan to migrate the feature into a dedicated package later.
+
+## Architecture
+- Browser-only plugin (no server code).
+- Core concept: a **typed registry** of `DiscoverFeature` entries.
+- The same registry instance is exposed on setup and start.
+
+Key files:
+- `public/plugin.ts`
+- `public/services/discover_features/discover_features_service.ts`
+- `public/services/discover_features/types.ts`
+- `common/features_registry/features_registry.ts`
+
+## Adding a feature
+1. Define a feature interface in `public/services/discover_features/types.ts`.
+2. Add it to the `DiscoverFeature` union.
+3. Register the feature from the owning plugin via `discoverShared.features.registry.register(...)`.
+4. Consume the feature in Discover via `getById(featureId)` and render it conditionally.
+
+## Constraints
+- Feature IDs must be unique (duplicate registration throws).
+- Do not use this as a general customization mechanism.
+- Keep contracts minimal and explicit to preserve type safety.
+
+## Testing
+- Unit tests live in `common/features_registry/features_registry.test.tsx`.
+- Use `public/mocks.ts` and `public/services/discover_features/discover_features_service.mock.ts` for test setup.
+- Example: `yarn test:jest src/platform/plugins/shared/discover_shared`
+- If a verifier sub-agent exists (e.g., `kibana-verifier` or `verifier`), run it and include its findings in the test notes.
+
+## Escalation
+If a change requires new feature contracts or impacts consuming plugins, coordinate with the owning teams before finalizing.
+
+## References
+- `src/platform/plugins/shared/discover_shared/README.md`
+- `src/platform/plugins/shared/discover/public/context_awareness/README.md`

src/platform/plugins/shared/esql/AGENTS.md

@@ -0,0 +1,156 @@
+---
+title: ES|QL Plugin Guide for Agents
+---
+
+# ES|QL (@kbn/esql)
+
+Shared plugin providing the ES|QL editor, triggers, and server-side extensions/auto-complete APIs.
+
+## Public API
+- Main component: `ESQLLangEditor` (`public/create_editor.tsx`)
+- Entry point: `public/index.ts`
+- Use when embedding ES|QL in apps (Lens, Maps, ML, Alerts, Unified Search).
+
+## Server API
+Server-side routes and extensions registry live under `server/`.
+Key routes include:
+- `/internal/esql/autocomplete/join/indices`
+- `/internal/esql/autocomplete/timeseries/indices`
+- `/internal/esql/autocomplete/inference_endpoints/{taskType}`
+- `/internal/esql_registry/extensions/{query}`
+
+Extensions registry:
+- Solution-scoped (es, oblt, security, workplaceai).
+- Only returns indices that exist in the instance.
+
+## Key concepts
+- ES|QL editor is UI-only; data fetching is owned by the consuming app.
+- Triggers for controls and query updates live in `public/triggers/`.
+- Registry is the integration point for recommended queries and fields.
+
+## Data flow and components
+```mermaid
+flowchart LR
+  subgraph Consumers["Consumers"]
+    App[Apps: Discover, Lens, Maps, ML, Alerts]
+  end
+
+  subgraph Public["kbn/esql public plugin"]
+    ESQLLangEditor[ESQLLangEditor]
+    ESQLEditor[ESQLEditor]
+    KibanaServices[Kibana services: core, data, uiActions, kql, fieldsMetadata, usageCollection]
+    VariablesService[Variables service]
+    Triggers[UI Actions triggers]
+    UpdateAction[Update query action]
+    ControlAction[Create control action]
+    ControlFlyout[Control flyout]
+    ChooseColumn[Choose column popover]
+    IdentifierForm[Identifier control form]
+    ValueForm[Value control form]
+  end
+
+  subgraph Server["kbn/esql server plugin"]
+    Routes[HTTP routes: autocomplete, extensions, lookup, timefield]
+    EsqlService[ESQL service]
+    ExtensionsRegistry[Extensions registry]
+  end
+
+  subgraph Elasticsearch["Elasticsearch"]
+    ES[indices resolveIndex and inference endpoints]
+  end
+
+  App --> ESQLLangEditor --> ESQLEditor
+  ESQLLangEditor --> KibanaServices
+  KibanaServices --> ESQLEditor
+  ESQLEditor -->|autocomplete / extensions / lookup| Routes
+  Routes --> EsqlService --> ES
+  Routes --> ExtensionsRegistry
+
+  ESQLEditor --> VariablesService
+  ESQLEditor --> Triggers
+  Triggers --> UpdateAction -->|set query| KibanaServices
+  Triggers --> ControlAction --> ControlFlyout --> ChooseColumn
+  ControlFlyout --> IdentifierForm
+  ControlFlyout --> ValueForm
+```
+
+## Change guidance
+- Add new commands using `ADD_COMMAND_GUIDE.md`.
+- Grammar updates come from Elasticsearch; keep changes isolated and well-tested.
+- Respect solution scoping when registering extensions.
+
+## Testing
+- Unit tests: `jest.config.js`
+- Integration tests: `jest.integration.config.js`
+- Tests live in `public/**`, `server/**`, and `server/integration_tests/**`.
+- Example: `yarn test:jest src/platform/plugins/shared/esql`
+- If a verifier sub-agent exists (e.g., `kibana-verifier` or `verifier`), run it and include its findings in the test notes.
+
+## Escalation
+If changes affect editor integrations or extension registry behavior, coordinate with the owning solution teams.
+
+## References
+- `src/platform/plugins/shared/esql/README.md`
+- `src/platform/plugins/shared/esql/server/README.md`
+- `src/platform/plugins/shared/esql/ADD_COMMAND_GUIDE.md`
+- `src/platform/packages/shared/kbn-esql-language/README.md`
+- `src/platform/packages/shared/kbn-esql-language/src/parser/README.md`
+- `src/platform/packages/shared/kbn-esql-language/src/language/README.md`
+- `src/platform/packages/shared/kbn-esql-language/src/commands/README.md`
+- `src/platform/packages/shared/kbn-esql-language/src/composer/README.md`
+
+## kbn-esql-language package guide
+Package location: `src/platform/packages/shared/kbn-esql-language`
+
+This package owns ES|QL parsing, AST utilities, and editor-facing language features
+used by the ES|QL plugin and other consumers.
+
+### What lives here
+- Parser (ANTLR-based) → CST/AST + syntax validation, highlighting metadata.
+- AST utilities: builder, walker, mutation, and pretty-printing.
+- Language features: validation, autocomplete, hover, signature help.
+- Commands: definitions and registry for ES|QL commands.
+- Composer API: safe, parameterized ES|QL builder for app code.
+
+### kbn-esql-language data flow
+```mermaid
+flowchart LR
+  Grammar["ESQL grammar (synced from Elasticsearch)"] --> Parser["Parser (ANTLR)"]
+  Query["ESQL query text"] --> Parser
+  Parser --> CST["CST"]
+  CST --> AST["ESQL AST"]
+
+  Builder["Builder API"] --> AST
+  Composer["Composer API"] --> AST
+  Walker["Walker/Mutate"] --> AST
+  AST --> PrettyPrint["Pretty printing"]
+
+  Definitions["Definitions"] --> Registry["Commands registry"]
+  Registry --> Validation["Validation"]
+  Registry --> Autocomplete["Autocomplete/Suggest"]
+  Callbacks["ESQL callbacks: sources/fields"] --> Validation
+  Callbacks --> Autocomplete
+
+  AST --> Validation
+  AST --> Autocomplete
+  AST --> Hover["Hover/Signature help"]
+```
+
+### Key behavior
+- Parser produces partial AST even with invalid queries; `withFormatting` attaches
+  comments/whitespace to nodes for editor features.
+- Validation can degrade gracefully when callbacks (sources/fields) are missing;
+  keep this in mind when wiring UI services.
+- Autocomplete works best-effort on invalid queries and may return empty results
+  when correction fails.
+- Composer prefers tagged templates with parameter holes to avoid injection.
+
+### Local demos
+- ES|QL AST Inspector: `yarn storybook esql_ast_inspector`
+- Kibana examples: `yarn start --run-examples` (navigate to ES|QL AST Inspector)
+
+### Testing
+- Whole package: `yarn test:jest src/platform/packages/shared/kbn-esql-language/`
+- Targeted: `yarn jest:tests src/platform/packages/shared/kbn-esql-language/path/to/test/file`
+- Validation tests update `src/validation/esql_validation_meta_tests.json` and should
+  be re-run when they change.

x-pack/platform/plugins/shared/lens/AGENTS.md

@@ -0,0 +1,43 @@
+---
+title: Lens Plugin Guide for Agents
+---
+
+# Lens (@kbn/lens-plugin)
+
+Lens is the visualization editor for Kibana. It supports embedding visualizations, editing in-app, and saved object persistence.
+
+## Architecture and entry points
+- Public plugin: `public/plugin.ts`
+- Server plugin: `server/plugin.tsx`
+- Main editor app: `public/app_plugin/app.tsx`
+- Embeddable: `public/react_embeddable/`
+- Datasources: `public/datasources/` (form-based + ES|QL)
+- Visualizations: `public/visualizations/`
+- State management: `public/state_management/` (Redux)
+
+## Embedding guidance
+Prefer, in order:
+1. **Dashboard** for most use cases (lowest maintenance).
+2. **Lens embeddable** via `EmbeddableComponent` and `navigateToPrefilledEditor`.
+3. **Custom rendering** only when Lens cannot support requirements.
+
+## Constraints and performance
+- Each embeddable fetches its own data; avoid many panels (> ~20) on one page.
+- Keep `attributes` stable (`useMemo`) to avoid re-initialization and refetching.
+- Experimental APIs may change without notice.
+
+## Testing
+- Unit tests: `x-pack/platform/plugins/shared/lens/jest.config.js`
+- Functional tests: `x-pack/platform/test/functional/apps/lens/`
+- API integration: `x-pack/platform/test/api_integration/apis/lens/`
+- Performance journeys: `x-pack/performance/journeys_e2e/data_stress_test_lens*`
+- Example: `yarn test:jest x-pack/platform/plugins/shared/lens`
+- If a verifier sub-agent exists (e.g., `kibana-verifier` or `verifier`), run it and include its findings in the test notes.
+
+## Escalation
+If changes impact shared visualization contracts or embeddable APIs, coordinate with the owning teams before finalizing.
+
+## References
+- `x-pack/platform/plugins/shared/lens/readme.md`
+- `x-pack/platform/test/functional/apps/lens/README.md`
+- `x-pack/examples/embedded_lens_example`