Generate a gomarkdoc API reference in the docs site build (P1b)

docs.yml now installs gomarkdoc and runs it over the packages meant
for external reuse (core/protocol/..., core/service/..., client/...,
plus the shared core/{csnet,binaryprimitives,config,fs,encoding,link,
buf} packages — adapter/* and cmd/* excluded as internal composition/
CLI layer), writing one page per package into site/content/reference/
with a minimal injected Hugo frontmatter. Also widen the workflow's
trigger paths to those source trees so the reference regenerates when
they change, and point Set up Go at the root go.mod (was site/go.mod)
so `go list`/`go install` run against the real module.

The generated pages aren't committed (gitignored, apart from the
hand-written _index.md landing page) — verified locally end-to-end:
ran the exact script, then `hugo --minify --gc` against the real repo
content, and confirmed the reference pages render with correct
per-package titles.

Author: pgodwin

.github/workflows/docs.yml

@@ -9,6 +9,16 @@ on:
       - "spec/**"
       - "ARCHITECTURE.md"
       - "site/**"
+      - "core/protocol/**"
+      - "core/service/**"
+      - "client/**"
+      - "core/csnet/**"
+      - "core/binaryprimitives/**"
+      - "core/config/**"
+      - "core/fs/**"
+      - "core/encoding/**"
+      - "core/link/**"
+      - "core/buf/**"
       - ".github/workflows/docs.yml"
   workflow_dispatch: {}
 
@@ -32,7 +42,35 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v6
         with:
-          go-version-file: site/go.mod
+          go-version-file: go.mod
+
+      - name: Generate API reference (gomarkdoc)
+        run: |
+          set -euo pipefail
+          go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@v1.1.0
+
+          # Packages meant for external reuse: protocol codecs, file/network
+          # services, the client SDK, and the shared support packages.
+          # adapter/* and cmd/* are ClassicStack's own composition/CLI layer,
+          # not reuse surface, so they're excluded.
+          MODULE=$(go list -m)
+          PKGS=$(go list -tags all \
+            ./core/protocol/... ./core/service/... ./client/... \
+            ./core/csnet/... ./core/binaryprimitives/... ./core/config/... \
+            ./core/fs/... ./core/encoding/... ./core/link/... ./core/buf/... \
+            | sed "s|^$MODULE/|./|")
+
+          mkdir -p site/content/reference
+          gomarkdoc --tags all -o 'site/content/reference/{{.Dir}}.md' $PKGS
+
+          # gomarkdoc's output carries no Hugo frontmatter; add a minimal one
+          # per page, titled from the "# <pkg>" heading gomarkdoc already wrote.
+          find site/content/reference -name '*.md' ! -name '_index.md' -print0 |
+            while IFS= read -r -d '' f; do
+              title=$(grep -m1 '^# ' "$f" | sed 's/^# //')
+              { printf -- '---\ntitle: "%s"\n---\n\n' "$title"; cat "$f"; } > "$f.tmp"
+              mv "$f.tmp" "$f"
+            done
 
       - name: Set up Hugo
         uses: peaceiris/actions-hugo@v3

.gitignore

@@ -49,6 +49,13 @@ vendor/
 go.work
 go.work.sum
 
+# Hugo build output and the gomarkdoc-generated API reference pages (docs.yml
+# regenerates both on every build; only site/content/reference/_index.md is
+# hand-written and tracked).
+/public/
+/site/content/reference/*
+!/site/content/reference/_index.md
+
 # env file
 .env
 

site/content/reference/_index.md

@@ -0,0 +1,22 @@
+---
+title: "API Reference"
+weight: 12
+---
+
+# API Reference
+
+Generated from Go doc comments (via [gomarkdoc](https://github.com/princjef/gomarkdoc)) for the
+packages meant for external reuse: the protocol codecs (`core/protocol/...`), the file/network
+services (`core/service/...`), the client SDK (`client/...`), and the shared support packages
+(`core/csnet`, `core/binaryprimitives`, `core/config`, `core/fs`, `core/encoding`, `core/link`,
+`core/buf`). See [§5](../docs/manual/#5-extending-classicstack--the-client-sdk) and
+[§6](../docs/manual/#6-extending-classicstack--the-server-sdk) of the manual for the guided
+walkthroughs these pages are the reference companion to.
+
+`adapter/*` and `cmd/*` are excluded — they are ClassicStack's own composition/CLI layer, not
+reuse surface for an external importer.
+
+This section is regenerated on every build; the pages under it are not stored in the repository.
+A thin or missing doc comment on a package shows up here as a thin page — if you're extending
+ClassicStack and a page is missing detail you need, that's a good sign the source package's doc
+comment could use it too.