docs(saved-objects): consolidate docs and document scoped vs system client

dev_docs/key_concepts/saved_objects.mdx

@@ -7,92 +7,6 @@ date: 2021-02-02
 tags: ['kibana', 'dev', 'contributor', 'api docs']
 ---
 
-"Saved Objects" are developer defined, persisted entities, stored in the Kibana system index (which is also sometimes referred to as the `.kibana` index).
-The Saved Objects service allows Kibana plugins to use Elasticsearch like a primary database. Think of it as an Object Document Mapper for Elasticsearch.
-Some examples of Saved Object types are dashboards, lens, canvas workpads, index patterns, cases, ml jobs, and advanced settings. Some Saved Object types are
-exposed to the user in the [Saved Object management UI](https://www.elastic.co/guide/en/kibana/current/managing-saved-objects.html), but not all.
-
-Developers create and manage their Saved Objects using the SavedObjectClient, while other data in Elasticsearch should be accessed via the data plugin's search
-services.
-
-![image](../assets/saved_object_vs_data_indices.png)
-
-<DocLink id="kibDevTutorialSavedObject" text="Tutorial: Register a new Saved Object type" />
-
-## References
-
-In order to support import and export, and space-sharing capabilities, Saved Objects need to explicitly list any references they contain to other Saved Objects.
-The parent should have a reference to it's children, not the other way around. That way when a "parent" is exported (or shared to a space),
-all the "children" will be automatically included. However, when a "child" is exported, it will not include all "parents".
-
-<DocLink
-  id="kibDevTutorialSavedObject"
-  section="references"
-  text="Learn how to define Saved Object references"
-/>
-
-## Migrations and Backward compatibility
-
-As your plugin evolves, you may need to change your Saved Object
-type in a breaking way (for example, changing the type of an attribute, or removing
-an attribute). If that happens, you should write a new model version to upgrade the Saved Objects that existed prior to the change.
-
-<DocLink id="kibDevTutorialSavedObject" section="migrations" text="Defining model versions" />.
-
-If you create or persist raw saved objects outside of Kibana (for example, via the deprecated Saved Objects HTTP CRUD APIs or NDJSON files), preserve `coreMigrationVersion` and `typeMigrationVersion` to retain forwards compatibility across Kibana versions. For more details, refer to the [Saved Objects](https://www.elastic.co/docs/extend/kibana/saved-objects) documentation.
-
-## Security
-
-Saved Objects can be secured using Kibana's Privileges model, unlike data that comes from data indices, which is secured using Elasticsearch's Privileges model.
-
-### Aggregation security
-
-When using the `find` or `search` methods with aggregations, be aware that certain Elasticsearch aggregation types can bypass query restrictions and return data from documents the user should not have access to. See <DocLink id="kibDevTutorialSavedObjectsSearch" section="security-considerations-for-aggregations" text="Security considerations for aggregations" /> for details on which aggregations to avoid.
-
-### Space awareness
-
-Saved Objects are "space aware". They exist in the space they were created in, and any spaces they have been shared with.
-
-### Feature controls and RBAC
-
-Feature controls provide another level of isolation and shareability for Saved Objects. Admins can give users and roles read, write or none permissions for each Saved Object type.
-
-### Object level security (OLS)
-
-OLS is an oft-requested feature that is not implemented yet. When it is, it will provide users with even more sharing and privacy flexibility. Individual
-objects can be private to the user, shared with a selection of others, or made public. Much like how sharing Google Docs works.
-
-## Scalability
-
-By default all saved object types go into a single index. If you expect your saved object type to have a lot of unique fields, or if you expect there
-to be many of them, you can have your objects go in a separate index by using the `indexPattern` field. Reporting and task manager are two
-examples of features that use this capability.
-
-## Searchability
-
-Because saved objects are stored in system indices, they cannot be searched like other data can. If you see the phrase “[X] as data” it is
-referring to this searching limitation. Users will not be able to create custom dashboards using saved object data, like they would for data stored
-in Elasticsearch data indices.
-
-## Saved Objects by value
-
-Sometimes Saved Objects end up persisted inside another Saved Object. We call these Saved Objects “by value”, as opposed to "by
-reference". If an end user creates a visualization and adds it to a dashboard without saving it to the visualization
-library, the data ends up nested inside the dashboard Saved Object. This helps keep the visualization library smaller. It also avoids
-issues with edits propagating - since an entity can only exist in a single place.
-Note that from the end user stand point, we don’t use these terms “by reference” and “by value”.
-
-## Sharing Saved Objects
-
-Starting in Kibana 7.12, saved objects can be shared to multiple spaces. The "space behavior" is determined for each object type depending
-on how it is registered.
-
-If you are adding a **new** object type, when you register it:
-
-1. Use `namespaceType: 'multiple-isolated'` to make these objects exist in exactly one space
-2. Use `namespaceType: 'multiple'` to make these objects exist in one _or more_ spaces
-3. Use `namespaceType: 'agnostic'` if you want these objects to always exist in all spaces
-
-If you have an **existing** "legacy" object type that is not shareable (using `namespaceType: 'single'`), see the [legacy developer guide
-for Sharing Saved Objects](https://www.elastic.co/docs/extend/kibana/saved-objects/share) for details on steps you need to take
-to make sure this is converted to `namespaceType: 'multiple-isolated'` or `namespaceType: 'multiple'` in the 8.0 release.
+::::{note}
+This page has moved. For up-to-date documentation on Saved Objects — including how to define and evolve types, perform CRUD operations, manage security and spaces, and choose between a scoped and a system client — see the **[Saved Objects](https://www.elastic.co/docs/extend/kibana/saved-objects)** section of the Kibana developer documentation.
+::::

docs/extend/saved-objects.md

@@ -26,6 +26,38 @@ By using Saved Objects your plugin can take advantage of the following features:
 When integrating with saved objects via the Saved Objects import/export APIs or the deprecated Saved Objects HTTP CRUD APIs, preserve `coreMigrationVersion` and `typeMigrationVersion` when persisting raw saved object documents outside of Kibana (for example, in JSON/NDJSON files). These fields are required to retain forwards compatibility across Kibana versions as saved object types evolve.
 :::::
 
+## Security [saved-objects-security]
+
+Saved Objects are secured using Kibana's privileges model, unlike data in {{es}} data indices, which is secured using {{es}}'s model.
+
+### Space awareness [saved-objects-space-awareness]
+
+Saved Objects are "space aware". Each object exists in the space it was created in, and any additional spaces it has been shared with. See [Share across spaces](saved-objects/share.md) for details.
+
+### Feature controls and RBAC [saved-objects-rbac]
+
+Feature controls provide another level of isolation for Saved Objects. Admins can grant users and roles read, write, or no access to each Saved Object type independently.
+
+### Object level security (OLS) [saved-objects-ols]
+
+OLS is a planned feature, not yet implemented. Once available, it will allow individual objects to be private to their owner, shared with selected users, or made fully public — similar to how sharing in Google Docs works.
+
+## Scalability [saved-objects-scalability]
+
+By default all Saved Object types share the same index. If you expect a type to have many unique fields or a large number of instances, store it in a dedicated index by setting the `indexPattern` field when registering the type. Reporting and Task Manager both use this capability.
+
+## Searchability [saved-objects-searchability]
+
+Saved Objects are stored in system indices and cannot be searched like regular {{es}} data. If you see the phrase "[X] as data", it refers to this limitation: users cannot build custom dashboards or visualizations over Saved Object data the way they can with data in ordinary {{es}} indices.
+
+## Saved Objects by value and by reference [saved-objects-by-value]
+
+A Saved Object can be embedded inside another Saved Object ("by value") rather than saved as a standalone item ("by reference"). For example, when a user adds a visualization to a dashboard without saving it to the library, the visualization data is nested inside the dashboard Saved Object. This keeps the library smaller and avoids unexpected propagation of edits, since the embedded object exists in exactly one place.
+
+Note: the terms "by value" and "by reference" are internal developer concepts and are not surfaced to end users.
+
+## Saved Objects documentation summary [saved-objects-sections]
+
 This documentation is organized into the following sections:
 
 * [Structure](saved-objects/structure.md) — Parts of a Saved Object type definition (name, index pattern, mappings, model versions) and the structure of a model version.

docs/extend/saved-objects/use.md

@@ -19,7 +19,7 @@ Core exposes the Saved Objects service to plugins as `core.savedObjects`:
 
 You need the **start** contract to create, read, update, or delete Saved Object documents. Typically you obtain a client (or repository) per request inside a route handler using the request from the handler.
 
-## Start contract: clients and repositories
+## Start contract: clients and repositories [saved-objects-service-start]
 
 **SavedObjectsServiceStart** (contracts.ts) exposes four methods. The first two return an object that implements **SavedObjectsClientContract** (defined in `src/core/packages/saved-objects/api-server/src/saved_objects_client.ts`). The other two return an object that implements **ISavedObjectsRepository** (defined in `src/core/packages/saved-objects/api-server/src/saved_objects_repository.ts`).
 
@@ -44,6 +44,17 @@ Creates a **Saved Objects client** that uses the **internal** Kibana user. It do
 * **Options:** `SavedObjectsClientProviderOptions` — `includedHiddenTypes?: string[]`, `excludedExtensions?: string[]`. The security extension is excluded regardless.
 * **When to use:** When you must perform Saved Object operations without a request or with system privileges. Do not use with a fake request to bypass security.
 
+::::{important}
+The internal client operates in the `default` space by default. To query Saved Objects across **all** spaces (for example, during a background cleanup job), pass `namespaces: ['*']` in the `find` options:
+
+```ts
+const client = savedObjectsStart.getUnsafeInternalClient();
+const result = await client.find({ type: 'my-type', namespaces: ['*'] });
+```
+
+Without `namespaces: ['*']`, the query is silently restricted to the `default` space and will miss objects in other spaces.
+::::
+
 ### createScopedRepository
 
 Creates a **repository** scoped to the given request. The repository has all client methods plus a few extra operations (see [Working with the SavedObjectsRepository](#working-with-the-savedobjectsrepository)). Use only when you need those repository-only methods with request context.
@@ -68,6 +79,24 @@ Creates a **repository** using the internal user, with no request context. Same
 
 If you are not sure, use the client. Prefer the **scoped** client for request handlers and the **internal** client for background or system operations.
 
+::::{warning}
+Do not manually instantiate `SavedObjectsClient` (or `SavedObjectsRepository`) by passing a non-default or custom repository directly. Clients obtained this way bypass the wrappers that provide security, spaces isolation, and encrypted saved object protections. Always obtain a client or repository through the methods exposed by [`SavedObjectsServiceStart`](#saved-objects-service-start).
+::::
+
+---
+
+## Security considerations [saved-objects-use-security]
+
+### Aggregation security [saved-objects-use-aggregation-security]
+
+When using `find` or `search` with aggregations, be aware that certain {{es}} aggregation types (for example, `terms` on a field that is only partially visible to the user) can bypass query restrictions and return data from documents the user should not be able to see.
+
+To avoid exposing data unintentionally:
+
+* Prefer aggregations on fields that are directly filterable in the current query.
+* Avoid `terms` aggregations on fields whose values could come from documents outside the user's access scope.
+* Review the {{es}} documentation on [document-level security and aggregations](docs-content://deploy-manage/users-roles/cluster-or-deployment-auth/controlling-access-at-document-field-level.md#document-level-security) before using aggregations in a security-sensitive context.
+
 ---
 
 ## Working with the SavedObjectsClient