Add AGENTS.md for src/core (elastic#253465)

## Summary

Add an `AGENTS.md` to `src/core` documenting sub-package naming
conventions (`-server`, `-server-internal`, `-browser`,
`-browser-internal`, `-mocks`, `common`), visibility rules, mock
patterns, and top-level re-export structure. Intended as a concise
reference for agents working in core.

Hopefully speeds agent based work up a little bit and saves some tokens.

## Test plan

- N/A — documentation only.

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

---------

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

Author: jloleysens

src/core/AGENTS.md

@@ -0,0 +1,34 @@
+# src/core
+
+Code lives in `src/core/packages/`, organized by domain (e.g., `http`, `elasticsearch`, `saved-objects`). Each domain contains sub-packages following a naming convention.
+
+## Sub-package suffixes
+
+| Suffix | Role | Visibility |
+|---|---|---|
+| `-server` | Public server-side types and contracts | `shared` |
+| `-server-internal` | Server-side implementation | `private` |
+| `-server-mocks` | Jest mocks for server contracts | `shared`, `devOnly` |
+| `-browser` | Public browser-side types and contracts | `shared` |
+| `-browser-internal` | Browser-side implementation | `private` |
+| `-browser-mocks` | Jest mocks for browser contracts | `shared`, `devOnly` |
+| `common` | Types/utilities shared across server and browser | `shared` |
+
+- `-server` / `-browser` packages export **types and pure utilities only**. No implementation.
+- `-internal` packages contain the implementation. They depend on the public API package, never the reverse.
+- `-mocks` packages depend on the public API types to produce typed mock objects.
+
+## Visibility
+
+Each package declares `visibility` in its `kibana.jsonc`:
+
+- **`shared`** — any package in Kibana may import it. Used for public API types (`-server`, `-browser`, `common`) and mocks (`-mocks`).
+- **`private`** — only other `src/core` packages may import it. Used for all `-internal` packages since they contain implementation details that should not leak to plugins.
+
+## KEEP THIS FILE UP TO DATE
+
+If you (agent working in `src/core`) notice a discrepancy between this document and the actual code while working in `src/core`, include a fix to this AGENTS.md as part of your changeset.
+
+## Related docs
+
+- `src/core/CONVENTIONS.md` — plugin structure, API design, and mock patterns

src/core/CONVENTIONS.md

@@ -9,6 +9,10 @@
     - [Usage Collection](#usage-collection)
     - [Saved Objects Types](#saved-objects-types)
   - [Naming conventions](#naming-conventions)
+- [Core API Conventions](#core-api-conventions)
+  - [Exposing API Types](#1-exposing-api-types)
+  - [API Structure and nesting](#2-api-structure-and-nesting)
+  - [Tests and mocks](#3-tests-and-mocks)
 
 ## Organisational Conventions
 ### Definition of done
@@ -40,16 +44,16 @@ All Kibana plugins built at Elastic should follow the same structure.
 my_plugin/
 ├── kibana.json
 ├── public
-│   ├── applications
-│   │   ├── my_app
-│   │   │   └── index.ts
-│   │   └── index.ts
-│   ├── services
-│   │   ├── my_service
-│   │   │   └── index.ts
-│   │   └── index.ts
-│   ├── index.ts
-│   └── plugin.ts
+│   ├── applications
+│   │   ├── my_app
+│   │   │   └── index.ts
+│   │   └── index.ts
+│   ├── services
+│   │   ├── my_service
+│   │   │   └── index.ts
+│   │   └── index.ts
+│   ├── index.ts
+│   └── plugin.ts
 └── server
     ├── routes
     │   └── index.ts
@@ -58,12 +62,12 @@ my_plugin/
     ├── saved_objects
     │   ├── index.ts
     │   └── my_type.ts
-    ├── services
-    │   ├── my_service
-    │   │   └── index.ts
-    │   └── index.ts
-    ├── index.ts
-    └── plugin.ts
+    ├── services
+    │   ├── my_service
+    │   │   └── index.ts
+    │   └── index.ts
+    ├── index.ts
+    └── plugin.ts
 ```
 - [Manifest file](/docs/development/core/server/kibana-plugin-core-server.pluginmanifest.md) should be defined on top level.
 - Both `server` and `public` should have an `index.ts` and a `plugin.ts` file:
@@ -363,3 +367,117 @@ Migration example from the legacy format is available in `src/core/MIGRATION_EXA
 
 Export start and setup contracts as `MyPluginStart` and `MyPluginSetup`.
 This avoids naming clashes, if everyone exported them simply as `Start` and `Setup`.
+
+## Core API Conventions
+
+The following conventions apply to development inside `src/core`. Although many
+may be more widely applicable, adoption within the rest of Kibana is not the
+primary objective.
+
+### 1. Exposing API Types
+
+The following applies to types that describe the entire surface area of Core
+APIs and does not apply to internal types.
+
+ - 1.1 All API types must be exported from the top-level `server` or `public`
+   directories.
+
+   ```ts
+   // -- good --
+   import { IRouter } from 'src/core/server';
+
+   // -- bad --
+   import { IRouter } from 'src/core/server/http/router.ts';
+   ```
+
+   > Why? This is required for generating documentation from our inline
+   > typescript doc comments, makes it easier for API consumers to find the
+   > relevant types and creates a clear distinction between external and
+   > internal types.
+
+ - 1.2 Classes must not be exposed directly. Instead, use a separate type,
+   prefixed with an 'I', to describe the public contract of the class.
+
+   ```ts
+   // -- good (alternative 1) --
+   /**
+    * @public
+    * {@link UiSettingsClient}
+    */
+   export type IUiSettingsClient = PublicContractOf<UiSettingsClient>;
+
+   /** internal only */
+   export class UiSettingsClient {
+     constructor(private setting: string) {}
+     /** Retrieve all settings */
+     public getSettings(): { return this.settings; }
+   };
+
+   // -- good (alternative 2) --
+      export interface IUiSettingsClient {
+     /** Retrieve all settings */
+     public getSettings(): string;
+   }
+
+   export class UiSettingsClient implements IUiSettingsClient {
+     public getSettings(): string;
+   }
+
+   // -- bad --
+   /** external */
+   export class UiSettingsClient {
+     constructor(private setting: string) {}
+     public getSettings(): { return this.settings; }
+   }
+   ```
+
+   > Why? Classes' private members form part of their type signature making it
+   > impossible to mock a dependency typed as a `class`.
+
+### 2. API Structure and nesting
+
+ - 2.1 Nest API methods into their own namespace only if we expect we will be
+   adding additional methods to that namespace.
+
+   ```ts
+   // good
+   core.overlays.openFlyout(...);
+   core.overlays.openModal(...);
+   core.overlays.banners.add(...);
+   core.overlays.banners.remove(...);
+   core.overlays.banners.replace(...);
+
+   // bad
+   core.overlays.flyouts.open(...);
+   core.overlays.modals.open(...);
+   ```
+
+   > Why? Nested namespaces should facilitate discovery and navigation for
+   > consumers of the API. Having namespaces with a single method, effectively
+   > hides the method under an additional layer without improving the
+   > organization. However, introducing namespaces early on can avoid API
+   > churn when we know related API methods will be introduced.
+
+### 3. Tests and mocks
+
+ - 3.1 Declare Jest mocks with a temporary variable to ensure types are
+   correctly inferred.
+
+   ```ts
+   // -- good --
+   const createMock = () => {
+     const mocked: jest.Mocked<IContextService> = {
+       start: jest.fn(),
+     };
+     mocked.start.mockReturnValue(createStartContractMock());
+     return mocked;
+   };
+   // -- bad --
+   const createMock = (): jest.Mocked<ContextServiceContract> => ({
+     start: jest.fn().mockReturnValue(createSetupContractMock()),
+   });
+   ```
+
+   > Why? Without the temporary variable, Jest types the `start` function as
+   > `jest<any, any>` and, as a result, doesn't typecheck the mock return
+   > value.