---
path: /studio/aja/search-and-discovery
surface: studio
domain: aja
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/aja/search-and-discovery/page.tsx
status: walked
last_walked:
  '2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data
  (2xx), console/page-errors, expected content, screenshot verified; live
  screen-reader, touch, offline, and telemetry-delivery checks pending a manual
  AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; body
  re-derived 2026-06-03 from current source (lane-console architecture)'
---

# Studio Aja · Search and Discovery

## Purpose

Admin lane console for the real field-weighted relevance ranker. The operator
supplies a reference-asset catalog (JSON array), a query, and an optional
required-tag filter; the lane ranks the catalog for the query (title weight 3 >
tag 2 > description 1), filters to the required tag when given, drops zero-score
items, and reads back the matched/total counts and the scored results with their
matched fields.

## Entry points

- **Direct URL / bookmark** — `/studio/aja/search-and-discovery`; metadata
  canonical to this path
- **Studio nav** — Domain-bridge studios section of `/studio`
- **Sibling quick-actions on this page**: Reference Video Library, Back to Studio
  (no breadcrumb panel on this route)
- **Operator surfacing** — see
  [`../../studio-overview.md`](../../studio-overview.md)

## Layout regions

`page.tsx` renders inside `<ShellLayout active="studio">`:

- **Workspace** (`<StudioAjaSearchAndDiscoveryWorkspace />`, archetype: LEAF):
  - `<h1>` (`WorkspaceHeading`) "Aja Search and Discovery Workspace"
  - Summary `<p data-aja-search-and-discovery-summary>` — discovery lane runs a
    real field-weighted relevance ranker (title 3 > tag 2 > description 1)
  - **Relevance Ranking Lane** (`<h2 data-aja-sd-lane-heading>` "Relevance
    Ranking Lane") — the live search form
- **Route Map panel** (`data-aja-search-and-discovery-route-map`): `<h2>Route
  Map</h2>` listing 5 entries from `STUDIO_AJA_SEARCH_AND_DISCOVERY_ROUTE_MAP`
  (primary, scenes, exports, revisions, governance)
- **Quick-action panel**: two `Link.quickAction` anchors — Reference Video
  Library, Back to Studio workspace index

## States

- [ ] **Loading** — GETs the ranker catalog on mount; renders
      `<p data-aja-sd-loading>` "Loading relevance ranker…"
- [ ] **Unauthorized** — 401/403 renders `data-aja-sd-unauthorized` ("Access
      restricted." + admin-scope message, default "Aja workspace scope required
      to rank the catalog.")
- [ ] **Error** — non-OK / malformed / unreachable renders `data-aja-sd-error`
      ("Could not load the relevance ranker." + reason)
- [ ] **Ready (form)** — success renders `data-aja-sd-engine-summary`,
      `data-aja-sd-weights` (field weights), and the `data-aja-sd-form`
- [ ] **Result** — a successful POST renders `data-aja-sd-result` with
      `data-aja-sd-headline` (matched/total) and a `data-aja-sd-results-list` of
      `data-aja-sd-result-row` (id · title · score · matched fields)
- [ ] **Validation / search error** — invalid/non-array items JSON or POST
      failure renders `data-aja-sd-search-error`
- [x] **Empty / Standalone PWA / offline** — N/A beyond the above; shell SSR,
      lane is a client fetch on mount

## Interactions

### Relevance Ranking Lane (`data-aja-sd-form`)

- [ ] **Catalog items** (`data-aja-sd-items`, textarea, aria-label "catalog
      items json", JSON array)
- [ ] **Query** (`data-aja-sd-query`, input, aria-label "query")
- [ ] **Required tag** (`data-aja-sd-tag`, input, aria-label "required tag",
      optional)
- [ ] **"Rank catalog"** (`data-aja-sd-submit`, submit) — fires
      `POST /v1/admin/aja/search-and-discovery/search` with `{ items, query,
      tag? }`

### Route Map panel

- [ ] **Route entries** (5 × `<article>`) — non-interactive path+purpose

### Quick-action panel

- [ ] **"Open Aja Reference Video Library workspace"** →
      `/studio/aja/reference-video-library`
- [ ] **"Back to Studio workspace index"** → `/studio`

## Data & contracts

- **Reads**: `GET /v1/admin/aja/search-and-discovery` on mount — catalog
  `{ summary, fieldWeights }`
- **Writes**: `POST /v1/admin/aja/search-and-discovery/search` — `{ items,
  query, tag? }` → `{ result }` (total, matched, results[])
- **Realtime**: none
- **Caching**: client `fetch` on mount with `cache: 'no-store'` and
  `buildBffAuthHeaders()`; SSR shell only
- **Auth/role check**: BFF endpoints admin-scoped + fail-closed (401/403 →
  unauthorized render); route behind the signed-in + studio proxy gate

## Cross-references

- Parent: [`../../studio-overview.md`](../../studio-overview.md)
- Shell:
  [`../../../shell/04-auth-session.md`](../../../shell/04-auth-session.md)
- Sibling routes:
  [`./studio-aja-reference-video-library.md`](./studio-aja-reference-video-library.md)
- Component sources:
  - `apps/oshun/web/src/components/studio/StudioAjaSearchAndDiscoveryWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioAjaSearchAndDiscoveryRouteMap.ts`

## Open questions / known gaps

- [ ] Route-map sub-routes are advertised but have no `page.tsx` in V1