b267e55f8c
- 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
84 lines
3.6 KiB
Markdown
84 lines
3.6 KiB
Markdown
# 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.
|
|
|
|
### 2.3 Navigation and depth
|
|
- 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 |
|