diff --git a/content/assets/diagrams/homelab-topology.svg b/content/assets/diagrams/homelab-topology.svg index dd9fa1e..7578e5e 100644 --- a/content/assets/diagrams/homelab-topology.svg +++ b/content/assets/diagrams/homelab-topology.svg @@ -2,6 +2,19 @@ Homelab topology: build host, runtime host and public edge Three hosts. The build host produces a release; the runtime host runs the site, the vector store, a workflow worker and the model gateway, all bound to loopback; the public edge terminates TLS and is the only host reachable from the internet. All three join one private mesh, and backups run in three tiers. + diff --git a/content/assets/diagrams/rag-pipeline.svg b/content/assets/diagrams/rag-pipeline.svg index b8b2b1d..652f0c0 100644 --- a/content/assets/diagrams/rag-pipeline.svg +++ b/content/assets/diagrams/rag-pipeline.svg @@ -2,6 +2,19 @@ Retrieval pipeline: ingest on top, four-node query path below Ingest reads content and estate notes, excludes secrets, chunks and tags each block, embeds through the model gateway and upserts into two Qdrant collections on loopback. The query path classifies the question, routes it to an area, retrieves with a payload filter, composes an answer from the retrieved context only, and verifies that every citation resolves to a page. + diff --git a/docs/phase-7-notes.md b/docs/phase-7-notes.md new file mode 100644 index 0000000..3fda184 --- /dev/null +++ b/docs/phase-7-notes.md @@ -0,0 +1,71 @@ +# Phase 7 — notes + +Running record for the visual layer (AUD-149). Each batch states what changed, +what it measures, and what it still needs. + +--- + +## Batch 1 — marks, area icons, client wall, two diagrams + +### What is in the tree + +| Piece | Where | Note | +|---|---|---| +| Technology marks | `internal/brand/` | 50 Simple Icons paths (CC0), inlined as 16 px `currentColor` SVG. No request, no font, no bundler. | +| Regenerator | `tools/gen_brand_icons.sh` | Development-time only. The generated Go file is committed, so `make build` never needs the network. | +| Area icons | `internal/web/templates/icons.templ` | Six marks drawn for this site, plus one for the evidence index. 24×24, 1.6 px stroke, `aria-hidden`. | +| Client wall | `content/history/l3/history-client-wall.md` + `.client-wall` in `site.css` | 45 names, one typeface, one size, one grid of equal tiles. No client mark is used, because none has been approved. | +| Diagrams | `content/assets/diagrams/` | Homelab topology and RAG pipeline. Both referenced from the page they explain. | +| Image sizing | `internal/content/markdown.go` | Every content image gets intrinsic `width`/`height`, `loading="lazy"`, `decoding="async"`. | +| Guard | `internal/site/site_test.go` | `TestImagesReserveTheirSpace` fails if an image ships without size or alt text. | +| Topbar | `site.css` | Two rows at desktop. One row overlapped the search form once the marks were added; Lighthouse `target-size` caught it. | +| Favicon | `internal/web/static/favicon.svg` | Stops the browser asking for a missing `/favicon.ico` (it was the only console error). | + +### Adding a technology mark + +1. Add the label → slug pair to `slugs` in `internal/brand/brand.go`. +2. Add the slug to `slugs()` in `tools/gen_brand_icons.sh` and run it. +3. `make dist`, then check the chip on the page. + +A technology with no published mark renders as text alone, on purpose: a chip +with a missing image would read as a broken page. + +### Adding an image + +- File goes under `content/assets/` (published at `/assets/...`). +- SVG needs explicit `width` and `height` on the root element; PNG and JPEG are + measured with `image.DecodeConfig`. Both give the page its reserved space. +- Alt text describes the thing, not the file name. +- The diagrams carry their own print style, so they print as ink on white. + +### Measurements (2026-10-28) + +Lighthouse 12.8.2, headless Chrome, against the local server on `127.0.0.1`. + +| Page | Mode | Performance | Accessibility | Best practices | SEO | CLS | +|---|---|---|---|---|---|---| +| Landing | mobile | 100 | 100 | 100 | 100 | 0 | +| Landing | desktop | 100 | 100 | 100 | 100 | 0 | +| Platform network (diagram) | mobile | 100 | 100 | 100 | 100 | 0 | +| AI retrieval (diagram) | desktop | 100 | 100 | 100 | 100 | 0 | +| Client wall | mobile | 100 | 100 | 100 | 100 | — | +| Edge audio artefact | mobile | 100 | 100 | 100 | 100 | — | + +Total page weight: landing 153 KiB, diagram page 105 KiB. Diagram files are 5.7 +KiB and 6.6 KiB; the stylesheet is 24 KiB; htmx is 51 KiB and is the largest +single asset. + +Two defects were found by measurement rather than by eye and fixed in this +batch: the desktop topbar overlap, and the missing favicon. + +### Still open — needs Sam + +| DoD line | State | What is needed | +|---|---|---| +| At least one real photograph in use | Not started | Which photographs may be used (Immich on `.35` is the likely source). Anything used is checked for people, address and screens in shot. | +| Two screenshots in use | Not started | Approval to capture Home Assistant, Gitea, TUIOS with agent panes, or Graphify's `graph.html`. Screens must contain nothing personal. | +| One recording, 30–60 s | Not started | Either Sam records it, or Sam approves a recording of the agent console. | +| Client wall marks | Deliberately absent | Official marks only, with Sam's approval. Nothing invented. | + +Nothing above is blocking the site: it ships, measures 100 across the board, and +every page works with the AI services stopped. diff --git a/internal/web/static/site.css b/internal/web/static/site.css index 5c7572c..2fc0573 100644 --- a/internal/web/static/site.css +++ b/internal/web/static/site.css @@ -1397,6 +1397,29 @@ figure.media figcaption { color: #222; } + /* The wall and the chips are surfaces, not decoration: on paper they go + white with a hairline, and the marks keep their shape in one ink. */ + .client-wall { + background: #bbb; + border-color: #bbb; + } + + .client-tile, + .tech-chip { + background: #fff; + border-color: #bbb; + } + + .client-name, + .tech-chip { + color: #111; + } + + .nav-mark, + .pillar-mark { + color: #000; + } + a { color: #000; border-bottom: 0;