# Website Integration Guide

You said this will run on your website — this file is the technical wiring guide connecting the prompt/knowledge architecture in this repo to an actual Claude API-backed chat feature.

## 1. Request assembly (per chat turn)

```
system  = 01-core/system-prompt.md content
          (static — load once, cache; do not regenerate per request)

messages = [
  { role: "user", content:
      "<client_context> ... engagement-scoped facts ... </client_context>\n"
    + "<knowledge_context> ... entries retrieved for this query ... </knowledge_context>\n"
    + "<user_query> the actual question the user typed </user_query>"
  },
  ...prior turns in this conversation...
]
```

- **`<client_context>`**: assembled from your engagement/client record for *this session only*. Never carry it across sessions belonging to different clients (see core prompt §12).
- **`<knowledge_context>`**: assembled by your retrieval step (see `02-knowledge-layer/schema.md` §4) — match on jurisdiction, domain, and topic relevance to the current query. Keep it tight; irrelevant entries dilute answer quality.
- Keep the three tags distinct so the model can reason about provenance (fact vs. law vs. question) exactly as the core prompt instructs it to.

## 2. Model and API basics

Use the current Claude model family via the Messages API with the assembled `system` field as above. (See the `claude-api` skill/reference in this Claude Code environment for current model IDs, pricing, and Messages API parameters if you're implementing the backend call yourself — don't hard-code a model ID into this document, since that's exactly the kind of fact this whole architecture is designed to keep out of static files.)

Recommended request-level settings:
- **Streaming on** for a chat UI — professional answers can be long; don't make users wait for the whole response.
- **Conversation history capped** per session to a reasonable window; summarize/trim older turns rather than growing unbounded context, especially since `<client_context>` may repeat each turn.
- **Temperature low-to-moderate** — this is a professional-accuracy use case, not a creative one; prefer deterministic, consistent phrasing of technical conclusions over varied/creative phrasing.

## 3. Retrieval step (before every call)

1. Extract topic/domain/jurisdiction signals from the user's message (and client context, if entity type/industry is known).
2. Query the knowledge store (`02-knowledge-layer/schema.md`) for matching entries.
3. Apply the conflict-resolution rule (schema.md §3) if multiple entries match.
4. Format matches into the `<knowledge_context>` block (schema.md §4), including the `STALE — verify before relying` flag where applicable.
5. If retrieval finds nothing relevant to a FREQUENT/HIGHLY_TIME_SENSITIVE aspect of the question, inject nothing for that aspect — the core prompt already knows to flag the gap rather than guess (§4).

## 4. Session and client isolation

- One conversation thread = one client/engagement context, never mixed (core prompt §12).
- Do not let your backend silently pull in a different client's context into the same thread, even for "similar entity" convenience — each thread's `<client_context>` should come from an explicit, current selection (e.g., which client/engagement the logged-in user picked for this session).
- If your site serves multiple staff users, scope client context to what that logged-in user is actually authorized to see — this is an access-control concern for your backend, not something the prompt can enforce.

## 5. Human-in-the-loop for `UPDATE KNOWLEDGE`

Strongly recommended: agent-proposed knowledge entries go into a **review queue**, not straight into the live store, at least for anything above STATIC category (per `02-knowledge-layer/update-protocol.md` §2). A junior/AI-assisted misread of a notification going live unreviewed is a real risk given how these figures get used downstream (tax computations, deadline advice).

## 6. UI / professional-liability considerations (non-prompt, but important)

- Display a persistent, unobtrusive notice that outputs are decision-support, not a substitute for the signing professional's own verification and judgment — this mirrors core prompt §0/§14 but should also live in the UI itself, not rely on the model repeating a disclaimer every message.
- Surface confidence labels (§8 of the core prompt: High confidence / Requires verification / Interpretive / Fact-dependent / Specialist review recommended) visually if you can parse them out of the response — e.g. a small badge — so a busy user doesn't have to read the caveat in full prose every time.
- Log conversations (with appropriate access control) — for a professional-practice tool, an audit trail of what the agent said, when, and against what knowledge-context snapshot is valuable if a conclusion is ever questioned later. Store the `<knowledge_context>` actually used with each response, not just the response — that's what lets you reconstruct *why* it said what it said if a rate later turns out to have been stale.

## 7. What NOT to do

- Don't bake current rates/dates into the `system` field "just to get started faster" — that's precisely the trap this whole architecture avoids; use the knowledge layer from day one, even if day one is just a hand-maintained JSON file (`02-knowledge-layer/update-protocol.md` §5).
- Don't let the frontend claim capabilities (live monitoring, automatic reminders, guaranteed-current data) the backend doesn't actually have — mismatched claims are exactly what core prompt §14 is trying to prevent from the model's side; keep the UI copy honest too.
- Don't skip the red-team checklist (`06-testing-redteam/redteam-checklist.md`) before launch — a public-facing website surface is exactly where adversarial/injection attempts (via pasted documents, uploaded files) will actually happen, not just in testing.
