docs: comprehensive documentation expansion

Add 4 new doc files (configuration reference, development guide, API
reference with full request/response schemas, database schema), expand
the README with a feature list and how-it-works walkthrough, fix
missing Firmware and Burn stages in architecture.md and test-suite.md,
add threshold engine and host-mode agent sections, and add godoc
comments to 11 packages and 6 model types.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

internal/api/agent_handlers.go

@@ -1,3 +1,5 @@
+// Package api contains the HTTP handlers for both the agent-facing
+// endpoints (/api/v1/runs/:id/*) and the browser-facing UI routes.
 package api
 
 import (

internal/config/config.go

@@ -1,3 +1,7 @@
+// Package config loads the orchestrator's YAML configuration file and
+// exposes typed structs for every config block. The ProfileRegistry
+// (quick/deep/soak) is built during Load from the vetting: and
+// profiles: top-level blocks.
 package config
 
 import (

internal/db/db.go

@@ -1,3 +1,6 @@
+// Package db opens the SQLite database and applies embedded SQL
+// migrations in filename order at startup. Uses modernc.org/sqlite
+// (pure Go, no cgo).
 package db
 
 import (

internal/events/events.go

@@ -1,3 +1,6 @@
+// Package events provides an in-process SSE fan-out hub. Browser
+// clients subscribe via GET /events; the orchestrator publishes
+// pre-rendered HTML fragments that HTMX swaps into the DOM.
 package events
 
 import (

internal/model/model.go

@@ -1,7 +1,11 @@
+// Package model defines the domain value types shared across the
+// orchestrator: Host, Run, Stage, SubStep, Measurement, and SpecDiff.
+// These are plain structs with no behaviour beyond state classification.
 package model
 
 import "time"
 
+// Host is a registered hardware node in the vetting cluster.
 type Host struct {
 	ID               int64
 	Name             string
@@ -17,6 +21,7 @@ type Host struct {
 	LastSeenAt       *time.Time // host-mode agent heartbeat; nil = never seen
 }
 
+// RunState is the current position of a run in the state machine.
 type RunState string
 
 const (
@@ -51,6 +56,7 @@ func (s RunState) IsTerminal() bool {
 	return false
 }
 
+// Run is a single vetting pass on a host, walking through the stage pipeline.
 type Run struct {
 	ID                int64
 	HostID            int64
@@ -68,6 +74,7 @@ type Run struct {
 	Profile           string // quick|deep|soak; empty is treated as "quick"
 }
 
+// StageState tracks whether a stage is pending, running, passed, failed, or skipped.
 type StageState string
 
 const (
@@ -78,6 +85,7 @@ const (
 	StageSkipped StageState = "skipped"
 )
 
+// Stage is a single test step within a run (e.g. SMART, CPUStress, Storage).
 type Stage struct {
 	ID          int64
 	RunID       int64
@@ -107,6 +115,7 @@ type SubStep struct {
 	SummaryJSON string
 }
 
+// Measurement is a single time-series sample from the thermal sidecar or a stage executor.
 type Measurement struct {
 	ID      int64
 	RunID   int64
@@ -118,6 +127,7 @@ type Measurement struct {
 	Unit    string
 }
 
+// SpecDiff records a single expected-vs-actual hardware divergence from SpecValidate.
 type SpecDiff struct {
 	ID       int64
 	RunID    int64

internal/orchestrator/statemachine.go

@@ -1,3 +1,6 @@
+// Package orchestrator contains the run state machine, dispatcher,
+// per-run runner, WoL sender, HMAC token issuer, threshold evaluator,
+// and iperf3 supervisor.
 package orchestrator
 
 import (

internal/pxe/dnsmasq.go

@@ -1,3 +1,6 @@
+// Package pxe supervises a dnsmasq subprocess for proxy-DHCP PXE
+// boot and generates per-MAC iPXE scripts that chainload the live
+// image with run-specific kernel cmdline parameters.
 package pxe
 
 import (

internal/store/hosts.go

@@ -1,3 +1,6 @@
+// Package store is the repository layer for the orchestrator's SQLite
+// database. Each store type (Hosts, Runs, Stages, etc.) wraps a
+// *sql.DB and exposes hand-written SQL queries — no ORM.
 package store
 
 import (

internal/web/embed.go

@@ -1,3 +1,5 @@
+// Package web embeds the static assets (CSS, JS) and compiled Templ
+// templates served by the orchestrator's HTTP routes.
 package web
 
 import "embed"