# 06 — Site Architecture ## The house pattern, plus one obligation Copy `pki.sgit.ai`; add the `/llms-full.txt` it lacks. And note the obligation this site carries that no sibling does: **a site called `llms.sgit.ai` will be read by more agents than any other page in the estate.** The agent-access report's finding — *"it can read the map and cannot walk it"* — is not a topic here, it is an acceptance criterion. `/llms.txt` must be **self-sufficient** rather than a link list, `/llms-full.txt` must exist, and the markdown twin must work at every path. --- ## Page by page ### `/` — the front page The thesis in one sentence: **"Your app calls a language model without ever holding an API key."** Then, immediately and on the same page, the qualification from `03__` §5 — the bridge protects the vault's key, and is **not yet** an egress boundary. A front page that makes the claim without the caveat is one click from being contradicted by the project's own brief. Then the three-surface decision table, because most readers will discover they need no code at all. ### `/chat-pane/` — **build first** `01__`. The decision table, the three surfaces, the honesty mechanisms as decisions-with-reasons, and the vault setup with its key tiers. **The one sentence to feature: *"Every existing vault app gets this without being changed."*** ### `/chat-pane/samples/` `code__chat-pane-samples.md`, verbatim. Eight samples plus the pre-ship checklist. **These must be runnable and kept runnable** — see §3. ### `/api/` `02__`. The full `sg.llm.*` reference: one page per call with signature, grant, errors and a sample. **And a `/api/traps/` page** — the 8190 chunking, `available()` before rendering, images clearing after one turn, estimates never shown as bills, `listen` never implied by `chat`. That page will be the most visited on the site. ### `/security/` `03__`. The four-layer ladder, the key tiers, the unfakeable recording indicator, cost integrity, **and the CSP gap in full**. Name Phase 4 as the fix and be clear it is not shipped. ### `/websites/` `04__`. The three options, honestly compared, with the recommendation and the `sg-llm-chat` component as the concrete deliverable. **Label this section as the thin half** — it is a gap to fill, not an asset to publish. ### `/provenance/`, `/openrouter/`, `/local/` `05__`. The 2024 OWASP talk forward; the provider-layer position; Ollama and offline. Three pages, in that order. ### `/agents/` The dual surface: the API as machine-readable JSON, **and** the estate's own agent-readability practice — `llms.txt`, the markdown twin, `for_llms` filenames, the Lambda@Edge mechanism. Cross-link `coding.sgit.ai` `05__` §5. ### `/shipped/` `00__` §5 unsoftened — the CSP gap, Phase 4, ViV parity, the audio-model constant — plus `05__` §6's table of what has not been built: **no evals, no structured-output spec, no model routing, no cost analysis despite a full ledger.** ### `/network/`, `/admin/` House pattern. Build order published unresolved with `08__`'s questions and tensions visible. --- ## 3. What must be generated, not written | Content | Source | |---|---| | The API reference | **generated from `AUTHORING.md`** — see `08__` Q1 | | Error-code table | generated from the same | | Code samples | **tested, not just published** — see below | | Corpus counts (442 OpenRouter files, 92 injection, etc.) | generated or dated | | Shipped / not-built | from the capability brief, with its date | **The samples need a test.** A code sample that has drifted from the API is worse than no sample, and this API is eight months old and still moving (`listen` and `imagePart` landed a day after the rest). The cheapest mechanism: **ship the samples as a real vault app** — one that exercises `available`, `chat`, streaming, `cancel`, `usage`, `models`, `imagePart` and `listen` — and publish it as both the demo and the test. It would also be the best possible demonstration of surface 3. --- ## 4. The demo the site should ship Everything above argues for one artefact: **a vault app that is the documentation.** - It exercises every call, so the samples are tested by existing. - It is openable by anyone with a read key, so the docs are runnable rather than readable. - It demonstrates surface 3 while the reader is one click from surfaces 1 and 2. - It is the estate's own pattern — *"the maps live in the source and are reviewable in a diff"* applied to an API reference. ⚠️ **With one condition, from `03__` §6:** a vault with an LLM key configured **carries a credential**, and publishing its read key shares the ability to spend it. So the demo vault needs a **`shared`-tier key with hard `maxCostPerSession` and `maxCallsPerSession` caps**, deliberately chosen for publication — or it needs to ask the visitor for their own key, which is the BYOK precedent from the Article 9 Lab and probably the right answer for a public demo. **Decide that before publishing the vault, not after.** `08__` Q4. --- This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).