# Jessica Manuals Knowledge

## What feeds the manuals knowledge layer
- Primary source: tenant-filtered exports from the shared `manuals-platform` package.
- Rocky consumes `manuals-platform/output/tenants/rocky-mountain-vending/manuals.json`.
- Rocky consumes `manuals-platform/output/tenants/rocky-mountain-vending/chunks.json`.
- If shared exports are missing in local development, the RMV app can still fall back to its in-repo builder.

## How the corpus is built
- The shared `manuals-platform` package scans the portfolio manuals tree, assigns tenant entitlements, and writes prebuilt artifacts.
- RMV loads the Rocky tenant artifact on first use after process start.
- Public Jessica retrieval is therefore consuming a tenant-filtered export rather than rebuilding the raw manuals corpus itself.

## How new manuals become searchable
- Add or update source PDFs under `manuals-data`.
- Rebuild the shared package artifacts from `manuals-platform` so tenant exports are refreshed.
- Restart the Next.js server or deployment so RMV reloads the updated tenant artifact on first use.

## Cache refresh behavior
- The shared package writes persistent JSON artifacts under `manuals-platform/output`.
- RMV still caches the loaded Rocky tenant artifact in memory.
- A manual cache reset helper exists in `lib/manuals-knowledge.ts` for future admin tooling or deploy hooks.
- Today, the simplest refresh flow is: rebuild shared artifacts, then restart the app.

## Observability
- The site chat route logs a metadata-only manuals retrieval summary before the xAI request.
- The logs include whether retrieval ran, top manual candidate IDs, top chunk citations, clarification state, risk flag, and any retrieval error.
- Full chunk text is not logged.

## Internal debug surface
- Internal endpoint: `GET /api/admin/manuals-knowledge`
- Auth: `x-admin-token` or `Authorization: Bearer <ADMIN_API_TOKEN>`
- Example query:
  - `query=RVV 660 service manual`
  - optional `manufacturer`
  - optional `model`
  - optional `manualId`
  - optional `page`
- The endpoint returns retrieval summary, matched manuals, top chunks, and citation context for internal inspection only.