Sam Rolfe
84fc585c91
One Go binary serves a pre-rendered site. No Node, no bundler, no node_modules:
htmx and the SSE extension are vendored files, Markdown and code highlighting
run at build time (goldmark + chroma), and the server only writes files.
Implements docs/phase-2-static-site.md:
2.1 service skeleton cmd/build (content -> dist), cmd/server (dist -> HTTP),
env-configured, 127.0.0.1:8096, /healthz with separate
static / ai / search readiness, --health-check probe,
deploy/compose.yml + deploy/Dockerfile at 120m
2.2 rendering templ components (Layout, Nav, PillarCard, Stage,
EvidenceTable, CodeBlock, Timeline, Footer);
`make generate` is a build step and is byte-stable
2.3 navigation six-area rail, <details> disclosure under 900px,
breadcrumbs, aria-current, L1/L2/L3 with artefact pages
2.4 stage panel internal/stage owns the contract; RouteDriver (fragment
swap) and SSEDriver (event stream) differ only in the
Binding, never in layout. fragment ids live in the
contract so route files, links and streamed frames agree
2.5 search SQLite FTS5 over titles and body, rebuilt by the build;
one handler returns a page without HTMX, a fragment with
it. Visitors' FTS operators are never honoured
2.6 quality floor print stylesheet, JS-off navigation, focus states,
semantic landmarks, dark default; security headers
Definition of Done evidence (see issue AUD-142):
A1 all pages 200 in a network namespace with no external route
one binary serves the site; make dist writes 45 pages, 86 fragments, 40 docs
templ generate is deterministic (md5 identical across runs)
6 L1 + 6 L2 pages, artefact pages reachable in <= 3 clicks
FTS5 returns sensible hits for zigbee / signage / routing (tested)
Lighthouse 100 performance and 100 accessibility, mobile and desktop
first byte well inside 100ms over loopback (test)
panel renders from a route driver and re-points at the stream untouched
print legible: /edge/ renders to a 3-page PDF with the print stylesheet
Also fixes found while finishing the build:
- reject "." / ".." path segments before ServeMux redirects them into a file
outside the asset directory (/static/../build.json now 404, was 307->200)
- make test is the real gate: go test ./... plus the validator self-test
79 lines
3.9 KiB
Markdown
79 lines
3.9 KiB
Markdown
# Ai Resume — Paperclip build directory
|
|
|
|
This is the **working directory for the Paperclip project `Resume Ai`**. Paperclip builds here. Everything needed to build is in this folder; nothing outside it is required.
|
|
|
|
## Relationship to the planning folder
|
|
|
|
| Folder | Holds | Status |
|
|
|---|---|---|
|
|
| `/home/sam/paseo/projects/resume_ai_system/` | The *why* — research, cull decisions, stack rationale, evidence notes, content drafts | **Planning. Not the build.** Sam works here |
|
|
| `/home/sam/paseo/projects/resume_ai_system_paperclip_build/` | The *what* — build spec, phase documents, reference material, and the site itself | **This folder. Paperclip works here** |
|
|
|
|
The planning folder is read-only reference. Do not edit it from here, and do not make the build depend on it — anything needed must be copied in.
|
|
|
|
## Start here
|
|
|
|
1. **`AGENTS.md`** — the build spec. Constraints, conventions, and the phase list. Read it before anything else.
|
|
2. **`docs/phase-N-*.md`** — one document per phase: work, Definition of Done, out of scope, risks.
|
|
3. **`reference/`** — frozen decisions, stack and budgets, content map, acceptance tests.
|
|
|
|
## Phases
|
|
|
|
| # | Phase | Ships |
|
|
|---|---|---|
|
|
| 1 | Content source of truth | `content/` + validator |
|
|
| 2 | Mode A static site | Browsable pre-rendered site, no AI |
|
|
| 3 | Public deployment | Live URL behind Caddy |
|
|
| 4 | Corpus and retrieval | `content/` → Qdrant |
|
|
| 5 | Mode B console | Streaming, cited answers |
|
|
| 6 | Guardrails, cost, kill switch | Safe to leave public |
|
|
| 7 | Polish | Logos, diagrams, code exhibits |
|
|
|
|
Order is deliberate. Content first (both renderers need it). **Deploy at Phase 3, not last** — a live half-built URL is worth more than a perfect site that never ships. AI after deployment so it can never block launch.
|
|
|
|
## Repository
|
|
|
|
This folder **is** the git working copy of `sam/ai-resume`. One repo, one product.
|
|
|
|
Previously held an abandoned Vite/React scaffold. It was replaced by this build spec; the history is retained because it honestly records the false start, and it is referenced in the site's "alternatives considered" content.
|
|
|
|
## Build and run
|
|
|
|
The site is one Go binary serving pre-rendered HTML. There is no Node, no bundler and no
|
|
`node_modules`; `go.sum` is the only dependency lock.
|
|
|
|
```sh
|
|
nix develop # go, templ, sqlite3, make, curl
|
|
make validate # content gate: front-matter against the frozen schema
|
|
make test # go test ./... plus the validator self-test
|
|
make dist # templ generate → bin/ → pre-rendered dist/
|
|
make dev # build, then serve on http://127.0.0.1:8096
|
|
```
|
|
|
|
`bin/resume-build` reads `content/` and writes `dist/` (pages, stage fragments, the fragment
|
|
manifest, the SQLite FTS5 index, assets). `bin/resume-server` serves `dist/` and never reads
|
|
`content/`, never calls a model, and never opens a socket to another service — that is what
|
|
keeps acceptance test A1 true.
|
|
|
|
The two things that are not files are `/search` (FTS5 over page titles and body text) and
|
|
`/api/stage/stream` (the presentation panel driven by an event stream instead of a route).
|
|
|
|
## Ground rules
|
|
|
|
- **Do not touch other systems.** No stopping containers, no editing other projects, no `nixos-rebuild`, no Caddy changes except the single block specified in Phase 3 — and that one Sam applies.
|
|
- **Mode A must work with every AI service stopped.** Hard gate.
|
|
- **Never invent facts about Sam's career.** If it is not in `reference/` or `content/`, ask.
|
|
- **Secrets** live in `~/.config/environment.d/` only.
|
|
- **All models** go through OmniRoute.
|
|
|
|
## Current state
|
|
|
|
- [x] Repo prepared, scaffold retired, build spec written
|
|
- [x] Phase 1 — content source of truth (40 documents across six areas, `make validate`)
|
|
- [x] Phase 2 — static site (`make dist`, 45 pages, 86 stage fragments, FTS5 search)
|
|
- [ ] Phase 3 — public deployment
|
|
- [ ] Phase 4 — corpus
|
|
- [ ] Phase 5 — AI overlay
|
|
- [ ] Phase 6 — guardrails
|
|
- [ ] Phase 7 — polish
|