# Static-Site Chat Proxy Requirements

## Decision

A static site can host the first external source-grounded chat shell and public package assets.

A static site must not hold or expose provider API keys.

Any external model API call requires a server-side boundary such as a serverless function, edge function, API gateway, small service, or local-only developer proxy.

Required credential rule:

```text
Never put provider API keys in GitHub Pages, public JavaScript, static HTML, repo files, or browser-visible configuration.
```

This is an implementation-gate evaluation note only. It does not build a chat UI, deploy a proxy, call an external model API, add credentials, configure Cloudflare, configure Supabase, add runtime provider execution, add vector search, add hosted retrieval, add a database, ingest private data, or create enterprise workflow integration.

## Purpose

Issue #159 evaluates whether the current GitHub Pages and static-site implementation can support a first external source-grounded chat proof while preserving credential safety and source-grounding discipline.

The answer is split:

- static hosting is sufficient for reader pages, a chat shell, public context files, source maps, manifests, reader links, local corpus browsing, and prompt export
- static hosting is not sufficient for secret-backed provider calls, API key protection, rate limiting, abuse controls, token and cost accounting, external pulse-check calls, uploads, persistence, or durable review records

The first proof should remain public-corpus-first and package-first. It should prove whether a lightweight chat shell can send selected approved source references to a server-side provider boundary and receive a cited answer or refusal.

## Static-Site-Only Capabilities

The current static-site pattern can support these first-proof capabilities without compute:

| Capability | Static-site fit | Boundary |
|---|---|---|
| Reader pages | Strong fit. Static HTML can remain the human reading surface. | Reader pages do not become the grounding authority by themselves. Source paths, context-pack files, manifests, and source maps remain the grounding substrate. |
| Chat shell | Strong fit for UI only. Static HTML, CSS, and JavaScript can render mode selection, source selection, message history for the session, and answer display. | The shell must not contain provider keys, hidden credentials, private corpus material, or provider-specific secrets. |
| Public context-pack files | Strong fit. The browser can load approved public context-pack files and metadata from static paths. | Only public, non-sensitive approved corpus material may be loaded in the external proof. |
| Artifact manifests | Strong fit. The shell can read manifest metadata to list artifacts, paths, versions, and public reader targets. | Manifest metadata is navigation and traceability evidence, not proof of enterprise approval. |
| Source maps | Strong fit. Static source maps can connect artifact IDs, section IDs, source paths, public paths, and context references. | Missing source-map entries must be treated as gaps, not inferred. |
| Public static HTML links | Strong fit. Answers can link back to stable public reader targets when available. | Reader links do not replace citations to source paths or context-pack references. |
| Local or client-side corpus browsing | Good fit for small public snapshots. The shell can filter artifacts, sections, glossary entries, and source refs locally. | Browser-side browsing should not become private retrieval, hidden ranking, or sensitive-data processing. |
| Prompt export or copyable prompt package | Good fit for no-proxy mode. The site can assemble selected public snippets into a copyable prompt package for manual testing elsewhere. | No-proxy mode cannot call providers and must clearly label exported prompts as operator-mediated test material. |

Static-only mode can be useful before any proxy exists. It can validate source selection, citation maps, reader links, and prompt packaging. It cannot validate real model-call behavior, credential handling, abuse controls, or cost controls.

## Capabilities Requiring Server-Side Compute

These responsibilities require a server-side boundary before any external proof calls a provider:

| Responsibility | Why static-only is insufficient |
|---|---|
| Provider API calls | Browser JavaScript would expose call shape, endpoints, and any credential or token placed in the client. |
| API key protection | Provider keys must live in a server-side secret store or local-only developer environment, not in repo files or browser-visible configuration. |
| Rate limiting | A public browser shell cannot enforce reliable per-origin, per-session, or per-IP limits by itself. |
| Allowed origin checks | The receiving API boundary must decide which site origins may call it. Client-side checks are not sufficient. |
| Abuse controls | The proxy needs request size limits, mode limits, corpus boundaries, denial behavior, and basic abuse detection. |
| Token and cost accounting | The boundary needs to estimate or record tokens, provider cost metadata, latency, and failure states without trusting the browser as the ledger. |
| Provider adapter isolation | Provider-specific request formatting, response normalization, error handling, and retries belong behind an adapter boundary. |
| External web pulse-check calls | Current external source lookups must be separately labeled and need their own citation and source-quality controls. |
| Future upload handling | Proposal uploads or submitted evidence create intake, storage, malware, data-class, and retention questions. |
| Future persistence or review records | Durable conversations, assessment records, reviewer notes, logs, and corpus snapshots require storage and retention decisions. |

Server-side compute is not required because the first proof needs a large backend. It is required because secrets and enforcement boundaries cannot be delegated to public static files.

## Candidate External Proof Architecture

```text
GitHub Pages or Cloudflare Pages static site
  -> hosts reader pages, context-pack, manifests, source maps, and chat UI shell

Browser chat UI
  -> loads public approved corpus metadata and selected context
  -> sends user query and selected source refs to server-side proxy

Serverless API proxy
  -> stores provider API key securely
  -> enforces allowed origin, rate limits, and basic abuse controls
  -> calls selected model adapter
  -> returns answer, citations, refusal, and token/cost metadata

Model provider
  -> OpenAI, Z.ai, Gemini, or other approved external test adapter
```

The serverless API proxy is the minimum real external-call boundary. It should receive only the user query, selected mode, selected public source references or snippets, citation map data, and optional routing hints. It should not accept arbitrary private documents, unrestricted URLs, hidden system prompts from the browser, or unbounded context.

## Minimum Proxy Contract

The first proxy contract should be narrow and source-bound.

Request shape:

- mode: Find, Explain, Assess, or explicit external pulse check
- user question or proposal text
- selected public source snippets or source references
- citation map entries
- reader target links where available
- refusal rules
- optional routing hint or model-tier hint

Response shape:

- answer text or refusal text
- cited source references
- reader links where available
- source-boundary statement
- generated-derivative label for assessment outputs
- uncertainty or missing-evidence fields when applicable
- provider-neutral token, cost, latency, and model-tier metadata where available

The proxy should return citations or a refusal. It should not return uncited Playbook-grounded answers.

## Candidate Implementation Targets

| Target | Fit for first proof | Tradeoff and boundary |
|---|---|---|
| Cloudflare Pages plus Functions or Workers | Strong candidate if a hosted proof is desired because static hosting and serverless API boundary can live in one platform pattern. | Cleanest single-platform proof path, but still needs platform approval, current-doc verification, origin controls, rate limits, secret setup outside the repo, and no deployment in this issue. |
| GitHub Pages plus separate proxy | Viable if the existing GitHub Pages site remains the reader and chat-shell host. | Lowest disruption to the current public site, but splits hosting from API enforcement and creates cross-origin, deployment, monitoring, and ownership seams. GitHub Pages alone cannot hold provider keys. |
| Vercel or Netlify function | Viable for a small serverless proxy when the static site can call a separate function endpoint. | Good generic serverless shape, but adds another platform, secret store, deployment path, allowed-origin controls, and vendor approval question. |
| Azure Function | Viable as a bridge toward Microsoft-native internal deployment if enterprise approval exists. | Better alignment with future Microsoft-native posture, but may add more setup than the first public proof needs and still must not imply enterprise approval. |
| Small container or app service | Viable when stronger control over runtime, logging, request limits, or provider adapters is required. | More operational burden than necessary for the smallest proof. Use only if serverless constraints block the proof. |
| Local-only developer proxy | Good for private technical testing with public corpus before hosted proof work. | Keeps secrets off the public static site and out of the repo, but does not create a public proof path or hosted operating pattern. |
| No-proxy static-only mode | Good for corpus browsing, source selection, reader links, and prompt export. | Cannot call a provider. Useful as a safe fallback and as a way to test the source package before credentials or runtime decisions exist. |

## Cloudflare Pages And Workers Evaluation

Cloudflare Pages plus Functions or Workers should be treated as a first-class proof candidate, not merely as a generic serverless option.

Architecture fit:

- Pages can host the static reader surface and chat shell.
- Pages Functions or Workers can provide the server-side API boundary.
- The platform pattern can keep static hosting, route handling, and edge function deployment close together.
- A single hosting pattern can reduce cross-origin complexity compared with GitHub Pages plus a separate proxy.

Credential posture:

- Public vendor documentation describes Cloudflare Workers and Pages Functions secret bindings for sensitive values such as API keys and auth tokens.
- For this repository, that platform capability is an unverified vendor claim, not a CLM-validated product claim and not enterprise approval.
- Workers or Functions secrets appear sufficient for first-proof screening only if the provider key is configured outside the repository, used only server-side, never returned to the browser, and paired with origin checks, rate limits, request limits, logging minimization, and provider adapter isolation.
- Secrets alone are not a complete security boundary.

Comparison against GitHub Pages plus separate proxy:

| Criterion | Cloudflare Pages plus Functions or Workers | GitHub Pages plus separate proxy |
|---|---|---|
| Static reader hosting | Can host the reader/chat shell in the same platform pattern. | Reuses the current static site pattern. |
| API boundary | Functions or Workers can sit beside the static shell. | Requires another hosted API surface. |
| Credential boundary | Provider keys can be held in a server-side secret mechanism if configured correctly outside the repo. | Provider keys must live in the separate proxy platform, never GitHub Pages. |
| Origin controls | Can potentially keep routes under one platform or domain pattern. | Must manage cross-origin behavior between GitHub Pages and proxy host. |
| Operational complexity | Lower for a greenfield proof if Cloudflare is approved for experimentation. | Lower for preserving the existing reader site, higher for proxy coordination. |
| Proof recommendation | Cleanest hosted proof path to evaluate next if platform use is allowed. | Best path if maintaining the current GitHub Pages reader surface is the priority. |

This issue does not deploy Cloudflare, configure Cloudflare secrets, implement Workers, implement Pages Functions, create Cloudflare routes, or approve Cloudflare for production or enterprise use.

## Supabase Optional Support-Infrastructure Evaluation

Supabase should remain optional support infrastructure for the first proof.

Potential future support roles:

| Capability | When it may be useful | First-proof posture |
|---|---|---|
| Auth | Needed if access must be limited to named users or reviewers. | Not required for a public/non-sensitive proof. |
| Object storage | Needed for proposal uploads, review packets, or corpus snapshots. | Not required unless uploads or durable snapshots are explicitly added. |
| Proposal uploads | Needed when users submit evidence artifacts for assessment. | Out of scope for the first proof. |
| Persistence | Needed for saved conversations, review records, decisions, or audit history. | Avoid for the first proof unless durable records are explicitly required. |
| Review records | Needed if assessment outputs enter a review workflow. | Out of scope because human approval workflow is not implemented here. |
| Logs | Needed for operational monitoring beyond minimal proxy metadata. | Keep logging minimal for first proof. |
| Corpus snapshots | Needed if approved corpus releases must be selected dynamically or retained by proof run. | Static context-pack and manifest files are enough for the first proof. |

Supabase should not be required for the first proof unless persistence, auth, upload handling, durable review records, logs, corpus snapshots, or database-backed state becomes explicit scope.

This issue does not configure Supabase, add Supabase credentials, create a Supabase project, integrate Supabase client code, add database tables, add storage buckets, add auth, add edge functions, or make Supabase part of the MVP.

## Model Adapter Posture

Provider and model choice should remain swappable behind the proxy.

Candidate adapters:

- OpenAI API
- Z.ai or GLM-class compatible endpoint
- Gemini API
- future local or open-weight adapter
- future Microsoft-native internal agent path

No adapter is endorsed as enterprise-approved by this note.

Adapter responsibilities:

- format provider-specific prompts and request fields
- enforce the selected mode and source-boundary instructions
- normalize answer, refusal, citation, token, cost, latency, and error metadata
- map provider failures into stable proxy errors
- keep provider-specific details out of the browser contract

The first proof should not hardcode one premium model assumption. It should preserve the workload-to-model routing posture from #158: use the weakest sufficient model, escalate only when ambiguity or consequence requires it, and keep deterministic validation separate from model output.

## Retrieval And Source-Grounding Posture

Keep the first proof simple:

```text
approved public corpus snapshot
  -> context-pack / manifest / source maps
  -> lightweight source selection
  -> model prompt with cited source snippets
  -> answer with citations or refusal
```

Allowed first-proof source surfaces:

- public AICD Markdown files approved for external use
- generated context-pack files
- `docs/artifact-manifest.json`
- product-architecture docs approved for public/non-sensitive proof use
- grounding rules
- glossary
- source maps
- public static HTML reader links
- validation receipts when approved source posture depends on them

Do not add vector database, graph database, hosted retrieval service, durable memory, connector ingestion, private corpus ingestion, or database-backed retrieval in this issue.

Lightweight source selection can be enough for the proof. The browser can list artifacts and sections from public metadata. The proxy can verify selected source refs against an allowed corpus list before calling the provider. If the selected source does not support the answer, the response should refuse.

## Security And Boundary Requirements

The first external proof must preserve these boundaries:

- use only public, non-sensitive approved corpus material
- do not use private company content
- do not put user secrets in the browser
- do not put provider API keys in GitHub Pages, public JavaScript, static HTML, repo files, or browser-visible configuration
- enforce allowed origins at the proxy
- enforce request size, rate, and basic abuse limits at the proxy
- keep logs minimal and avoid storing full prompts or user submissions unless explicit review scope approves it
- return token, cost, latency, and model-tier metadata where available
- isolate provider adapters behind the proxy
- refuse when source evidence is missing
- keep external pulse-check behavior separate from Playbook-grounded answers

Required refusal patterns remain:

```text
Not found in the approved playbook package.
```

```text
The playbook provides guidance, but it does not approve this tool, data class, workflow, production use, or company policy.
```

```text
The submitted proposal lacks enough evidence to assess this criterion.
```

External pulse-check mode must be explicit, separately labeled, and separately cited. It must not silently overwrite or extend Playbook-grounded guidance.

## Stable Reader Targets

The chat shell and proxy response contract should inform issue #88 stable reader target work.

Answers should prefer citations that include:

1. artifact ID and title
2. section ID and section title where available
3. source path
4. context-pack path or source-map reference
5. claim ID or source-boundary note when relevant
6. public reader target link when stable

If a stable reader target is missing, the answer should cite the source path or context-pack reference and state that no stable reader link is available.

## Relationship To Existing Issues

| Issue | Relationship |
|---|---|
| #153 | Builds on the source-grounded semantic explainer by preserving Find, Explain, Assess, citations, refusals, generated-derivative labels, and field-guidance-not-policy boundaries. |
| #156 | Builds on the external API-backed reference implementation by defining the static-site and serverless proxy gate needed before real external provider calls. |
| #158 | Uses workload-to-model routing discipline by keeping provider adapters swappable, preserving token/cost visibility, and avoiding a default premium-model assumption. |
| #155 | Complements the Microsoft-native internal pilot by proving the portable behavior contract without replacing the internal deployment path. |
| #79 | Keeps backend, graph, vector, hosted retrieval, connector ingestion, durable-memory, and database evaluation deferred until package-first testing proves need. |
| #78 | Informs the assistant prototype by defining the minimum safe architecture for an external source-grounded proof. |
| #88 | Should inform stable reader targets because cited answers need durable public reader links where available. |
| #151 | Does not supersede DOCX rebuild idempotence, which remains separate deterministic artifact-generation hygiene. |
| #159 | This note implements the #159 evaluation only. |

## Non-Goals

This issue does not:

- build the chat UI
- deploy a proxy
- call external model APIs
- add credentials
- add runtime provider or model execution
- add vector search or database infrastructure
- add hosted retrieval service
- ingest private or company-sensitive data
- replace #156 or #158
- deploy to Cloudflare
- configure Cloudflare secrets
- implement Workers or Pages Functions
- integrate Supabase
- create Supabase auth, storage, database, logs, corpus snapshots, or edge functions
- add connector ingestion
- add durable memory
- add enterprise workflow integration
- approve any provider, model, tool, data class, workflow, production use, policy posture, security posture, legal posture, regulatory posture, or GxP use case

## Implementation-Gate Outcome

The current static-site implementation can support a safe no-proxy proof of source selection, corpus browsing, reader links, and prompt export.

The first real external chat proof needs a server-side boundary before any model API call.

The cleanest hosted proof path to evaluate next is Cloudflare Pages plus Functions or Workers if Cloudflare use is allowed for experimentation, because static hosting and server-side proxy can live in one platform pattern. The least disruptive path for the current published reader site is GitHub Pages plus a separate proxy. Supabase should remain optional and deferred unless auth, uploads, persistence, durable review records, logs, corpus snapshots, or database-backed state becomes explicit scope.

All platform-specific capability statements in this note are implementation-screening assumptions, not CLM-validated vendor claims or enterprise approval. A future implementation ticket must re-check current platform documentation, record credential handling evidence, and validate the chosen target before any deployment.