## Context

The indexing path now builds embeddings from structured text:

```text
Title: {title}
Path: {breadcrumb}
Content:
{content}
```

The persisted Milvus `content` field remains the raw chunk content. This improves semantic recall for section-aware questions, but only after documents are reindexed. Existing vectors were generated from the previous content-only input and cannot reflect the new breadcrumb signal.

The repository already has an offline fixture-based retrieval baseline. That baseline is useful for deterministic regression checks, but it does not prove that the live Milvus/Zilliz collection has been reindexed or that the running service returns breadcrumb-aware results.

## Goals / Non-Goals

**Goals:**

- Provide an explicit post-reindex live acceptance flow.
- Make the reindex prerequisite visible in documentation.
- Add a small script that calls the live retrieval endpoint with representative queries and writes reviewable reports.
- Keep the live flow optional so unit tests and offline evaluation remain service-free.

**Non-Goals:**

- Do not add a new reindex API in this change.
- Do not automatically mutate live Milvus/Zilliz data from the acceptance script.
- Do not change `lookup_knowledge`, VectorStore retrieval, or Milvus schema.
- Do not commit environment-specific live results unless they were intentionally captured for interview evidence.

## Decisions

### Decision 1: Keep Reindex Manual And Explicit

The acceptance flow documents that reindexing must happen before live validation, but it does not perform the reindex itself.

Rationale:

- Reindexing is a data mutation and can be slow or environment-specific.
- The existing project already has indexing paths through upload, document management, and knowledge-base initialization.
- Keeping mutation separate from validation makes failures easier to diagnose.

Alternative considered: add a script that triggers reindex and then validates. This was rejected for now because it would need environment-specific credentials, source selection, and safety controls.

### Decision 2: Use HTTP Endpoint Validation

The script calls `/api/search/similar` instead of invoking Java services directly.

Rationale:

- It validates the same runtime path used in demos.
- It works across SDK, Spring AI, and auto retrieval modes.
- It produces a simple artifact that can be shown in interview material.

Alternative considered: add a Java integration test. This was rejected because live Milvus and Spring Boot availability should remain optional.

### Decision 3: Preserve Offline Baseline Separately

The existing fixture-based evaluator remains the deterministic baseline. The new live acceptance flow is a smoke/regression companion, not a replacement.

Rationale:

- Offline reports are stable and CI-friendly.
- Live reports prove environment readiness and post-reindex behavior.
- Keeping both avoids mixing deterministic fixture checks with external-service validation.

## Risks / Trade-offs

- [Risk] Live results vary by environment, indexed documents, and retrieval mode. -> Mitigation: report the base URL, query set, result count, top candidates, score labels, and timestamp.
- [Risk] A developer may run live validation before reindexing. -> Mitigation: document the prerequisite clearly and include a report note.
- [Risk] The script could be mistaken for a benchmark. -> Mitigation: position it as acceptance smoke coverage; keep offline baseline for deterministic metrics.