docs(modules): rewrite lagoon, tide, pact, party, boardwalk, fetchguard READMEs

modules/boardwalk/README.md

@@ -1,3 +1,60 @@
 # boardwalk
 
-`boardwalk` serves the embedded admin SPA, including its configured path prefix, client-route fallback, cache headers, and API miss handoff. `cabana` imports it while activating admin routes; use `boardwalk.Handler` from `boardwalk.go`.
+HTTP handler that serves the embedded admin SPA build under a configurable path prefix.
+
+`import "git.golem15.com/golem15/summercms/modules/boardwalk"`
+
+## Overview
+
+`boardwalk` embeds the compiled admin SPA (`dist/`, produced by `npm --prefix admin run build`) into the binary and serves it. The build is path-agnostic: `index.html` carries a placeholder token that the handler replaces once, at construction, with the prefix the admin is mounted under, so one build works at any backend URI. [cabana](../cabana/README.md) mounts it when it activates the admin routes. It stands in for the server-rendered backend layouts of WinterCMS, which the Go port replaces with a single-page app.
+
+## Features
+
+- Serves the embedded build under any prefix, rewriting relative asset URLs and the admin base meta in `index.html` for that prefix (`boardwalk.RewriteIndex`).
+- Fails at boot when `index.html` lacks the `boardwalk.BaseToken` placeholder, which catches a stale or hand-edited build.
+- Falls back to `index.html` for client-side routes and directories; missing files with an extension get a plain 404.
+- Hands every request whose path under the prefix is `api` or starts with `api/` to a caller-supplied handler, so admin API misses stay JSON instead of returning the SPA.
+- Long-lived immutable caching for hashed files under `assets/`, `no-cache` for other files and `no-store` for `index.html`.
+- Security headers on every response: a restrictive Content-Security-Policy, frame denial, `nosniff`, a same-origin referrer policy and `noindex, nofollow`.
+- Explicit content types for scripts, styles, fonts, SVG and JSON, with a MIME lookup fallback.
+
+## Usage
+
+```go
+notFoundAPI := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusNotFound)
+	_, _ = w.Write([]byte(`{"error":"not found"}`))
+})
+
+spa, err := boardwalk.Handler("/backend", notFoundAPI)
+if err != nil {
+	return err
+}
+mux.Handle("/backend/", spa)
+```
+
+## API reference
+
+| Identifier | Description |
+|------------|-------------|
+| `boardwalk.Handler` | Builds the SPA handler for a prefix; the second argument answers unmatched `api/` paths. |
+| `boardwalk.Dist` | Returns the embedded build as an `fs.FS` rooted at `dist/`. |
+| `boardwalk.RewriteIndex` | Rewrites raw `index.html` bytes for a prefix; errors when the placeholder token is missing. |
+| `boardwalk.BaseToken` | The placeholder in `dist/index.html` that is replaced by the prefix. |
+
+## Dependencies
+
+- SummerCMS modules: none.
+- Third-party: none.
+- Standard library: `bytes`, `embed`, `errors`, `fmt`, `html`, `io/fs`, `mime`, `net/http`, `path`, `strings`, `time`.
+
+The embedded `dist/` tree is generated from the `admin/` Vite project, whose build writes to `modules/boardwalk/dist`.
+
+## Testing
+
+```sh
+go test ./modules/boardwalk/...
+```
+
+The tests run the handler through `net/http/httptest` against the embedded build and in-memory file systems; they need no external services.