doc: define the REST v2 URL shape for multi-entity domains

The search URL rules assumed one entity per sub-app, so `/v2/{entity}/search` had no
reading for a domain that groups several entities — `scheduling-history` holds session,
kernel, deployment, and route histories. Pin the entity as its own segment under the
domain prefix, with the qualifier attached to the entity.

Also state explicitly that the admin variant carries no path qualifier; only `scoped`
and `my` appear as segments.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jopemachine

src/ai/backend/manager/api/rest/v2/AGENTS.md

@@ -38,6 +38,16 @@ REST v2 Handler → Adapter (api/adapters/) → Processor → Service → Reposi
 - `POST /v2/{entity}/search`: superadmin only, no scope — system-wide query.
 - scoped search (non-admin): scope required — query within that scope.
 - There is no "unscoped system-wide query" for non-admins.
+- The admin variant takes **no path qualifier** — it is `/search`, not `/admin/search`. Only `scoped` and `my`
+  appear as qualifier segments.
+
+**domains that group several entities:**
+- When a sub-app covers more than one entity, the entity is its own segment under the domain prefix:
+  `/v2/{domain}/{entity}/{qualifier}/{operation}`.
+  Example: `/v2/scheduling-history/kernels/search` and `/v2/scheduling-history/kernels/scoped/search`.
+- The qualifier (`scoped`, `my`) always follows the entity, never the domain —
+  `/v2/scheduling-history/kernels/scoped/search`, not `/v2/scheduling-history/scoped/kernels/search`.
+- Everything else on this page reads `{entity}` as this `{domain}/{entity}` pair for such sub-apps.
 
 **scoped search URL** (under consideration):
 - Current: `POST /v2/{entity}/{scope_type}/{scope_id}/search` — express the scope as a nested resource path (not `search-by-{scope}`).

src/ai/backend/manager/api/rest/v2/CONTEXTS.md

@@ -24,6 +24,20 @@ class V2DomainHandler:
 - `POST /v2/users/projects/{project_id}/search` — users within a project
 - `POST /v2/users/roles/{role_id}/search` — users with a specific role
 
+## Multi-entity domains
+
+Some sub-apps cover several entities rather than one. `scheduling-history` is the clearest case: one
+domain holding session, kernel, deployment, and route histories. The entity becomes its own segment
+under the domain prefix, and the qualifier attaches to the entity:
+
+- `POST /v2/scheduling-history/kernels/search` — admin, system-wide
+- `POST /v2/scheduling-history/kernels/scoped/search` — scoped, `auth_required`
+
+Reading the domain as the entity instead (`/v2/scheduling-history/scoped/search`) would make the
+qualifier apply to all four histories at once, which is not what the caller is asking for. Splitting
+the domain apart (`/v2/kernel-scheduling-histories/search`) loses the grouping that makes the four
+histories discoverable as one feature.
+
 ## Pagination mode behavior
 
 search endpoints accept both cursor and offset pagination arguments.