Files

Sam Rolfe b267e55f8c Replace Vite/React scaffold with Go build spec

- AGENTS.md: build spec for Paperclip (constraints, conventions, 7 phases)
- docs/phase-1..7: per-phase work, DoD, out-of-scope, risks
- reference/: frozen decisions, stack+ports+budgets, content map, acceptance tests
- agents/: persona and security policy drafts
- Retires the React scaffold; history retained as record of the false start

2026-10-26 16:02:35 +11:00

3.6 KiB

Raw Blame History

Phase 2 — Mode A static site

Goal: a fast, browsable, pre-rendered site served by one Go binary, working with every AI service stopped.

Depends on: Phase 1 (content + schema).

Work

2.1 Service skeleton

Go module, net/http or chi, config from environment (no flags-only config).
/healthz returning separate readiness for static (always) and AI (separate field).
Bind 127.0.0.1:8096.
Compose file with mem_limit = memswap_limit = 120m, log rotation, restart policy.

2.2 Rendering

templ components: Layout, Nav, PillarCard, Stage, EvidenceTable, CodeBlock, Timeline, Footer.
templ generate wired into make build / go generate.
Server-side Markdown (goldmark) and code highlighting (chroma). No client-side rendering of content.
Static pre-render: content → HTML at build time. The binary serves files; it does not render per request for Mode A.

Left nav on desktop, hamburger below 900 px. Six areas from reference/content-map.md.
L1 → L2 → L3 drill-down, ≤ 3 clicks from landing to any artefact.
Breadcrumbs. Visible current-location state. Keyboard navigable.

2.4 The stage panel — build it as a content sink

This is the important design decision. The presentation panel takes content from a driver:

Stage ← driver(route)      // Mode A: HTMX fragment swap
Stage ← driver(SSE)        // Mode B: streamed response (Phase 5)

Build it generic now. If it is built as a page renderer, Phase 5 becomes a rewrite.

Panel clears on navigation and on a new AI response.
Panel accepts: text, code block, image, video, diagram, link list.
HTMX handles fragment swaps and the panel-cleared event.

2.5 Search and cache

SQLite + FTS5 over page titles and body text. Keyword search across the static site.
This same FTS5 index is the keyword half of Phase 4's hybrid retrieval. Build it once, here.

2.6 Quality floor

Print stylesheet.
Works with JavaScript disabled (nav degrades to links; search degrades to a form post).
Focus states, contrast, semantic landmarks.
Dark theme by default, matching Sam's existing design language.

Definition of Done

A1: with Qdrant, OmniRoute and any query service stopped, every page renders correctly.
One binary serves the whole site; no Node, no bundler, no node_modules in the repo.
templ generate produces no diff on a clean checkout (build is reproducible).
L1 (6) and L2 (6) pages complete, L3 stubs reachable in ≤ 3 clicks.
FTS5 search returns sensible results for "zigbee", "signage", "routing".
Lighthouse ≥ 95 performance and ≥ 95 accessibility, mobile and desktop.
First byte < 100 ms over LAN.
Stage panel renders from a route driver and can be re-pointed at a stream without touching layout code.
Prints legibly.

Out of scope

Any AI call, embedding, vector store or model integration.
Deployment (Phase 3).
Logos and final diagrams (Phase 7) — use typographic placeholders.

Risks

Risk	Mitigation
`templ` friction mid-build	It is a build-time codegen step, not a framework. If it genuinely blocks, stop and ask — do not silently switch to `html/template`
Panel built as a page renderer	§2.4 is a design contract. Review this before writing layout code
Design invented from scratch	Reuse Sam's existing dark surface/type language from the retired `sam-*` sites
Scope creep into interactivity	If it needs client state beyond the console, it is Phase 5's problem, not Phase 2's

3.6 KiB Raw Blame History