Adds hugo stack.

docs/stacks/hugo.md

@@ -0,0 +1,96 @@
+# Hugo static sites in Castle
+
+> **This is a stack — creation-time guidance for writing _new_ sites.**
+> A stack is a template + conventions, not a runtime requirement. `castle program
+> create --stack hugo` scaffolds from it (via Hugo's own `hugo new site`) and seeds
+> the program's default build verb. An existing Hugo site adopted with `castle
+> program add` doesn't need this stack — it declares its own `commands:` /
+> `build:`. See @docs/registry.md for `commands:`, `stack:` (optional), and `repo:`.
+
+How to build, serve, and manage [Hugo](https://gohugo.io) sites as castle programs.
+
+## Stack
+
+- Generator: Hugo (extended recommended — needed for SCSS/asset processing)
+- Build: `hugo --gc --minify` → `public/`
+- Served: `manager: caddy` static deployment, in place at `<name>.<gateway.domain>`
+- Package manager (only if a theme needs an asset pipeline): pnpm
+
+Hugo has one meaningful dev verb — **build**. It has no native lint/test/type-check,
+so the stack advertises only `build` / `install` / `uninstall`; `castle check` and
+friends aren't offered (a site can still declare its own, e.g. an HTML linter, under
+`commands:` — a declared verb always wins over the stack).
+
+## Create a new site
+
+```bash
+castle program create my-site --stack hugo --description "My site"
+cd /data/repos/my-site
+castle program build my-site      # hugo --gc --minify -> public/
+castle apply my-site              # serve at my-site.<gateway.domain>
+```
+
+The scaffold delegates the canonical skeleton to `hugo new site` (archetypes/,
+content/, layouts/, static/, themes/, hugo.toml) and overlays the pieces a bare
+skeleton lacks: minimal `layouts/` so the site **builds and serves without a
+theme**, an example `content/posts/hello.md`, a castle-flavored `hugo.toml`
+(`baseURL = "/"`, so assets resolve at the root of the site's own subdomain), and a
+`.gitignore` for the regenerated `public/` and `resources/`.
+
+Develop with the live server:
+
+```bash
+hugo server -D        # http://localhost:1313, rebuilds on save
+```
+
+## Adding a theme
+
+Drop a theme under `themes/` (usually a git submodule) and set `theme` in
+`hugo.toml`:
+
+```bash
+git submodule add https://github.com/<owner>/<theme>.git themes/<theme>
+```
+
+Themes with an **asset pipeline** (e.g. Blowfish + Tailwind) need a pre-build step
+before `hugo`. Declare it as a two-step `build` in `programs/<name>.yaml` — a
+declared `build.commands` overrides the stack's single-step default:
+
+```yaml
+build:
+  commands:
+    - [pnpm, build]          # compile the theme's CSS/JS
+    - [hugo, --gc, --minify] # render the site -> public/
+  outputs: [public]
+```
+
+One-time setup those themes expect (run once in the source tree):
+
+```bash
+git submodule update --init --recursive
+cd themes/<theme> && pnpm install
+```
+
+## Deployment shape
+
+`castle program create --stack hugo` writes:
+
+- **`programs/<name>.yaml`** — `source`, `stack: hugo`, `build.outputs: [public]`.
+- **`deployments/statics/<name>.yaml`** — `manager: caddy`, `root: public`,
+  `reach: internal` (flip to `public` to also expose over the tunnel).
+
+The gateway serves `<source>/public` in place — no copy, no Node/Hugo process at
+runtime. `castle program build` regenerates `public/`; `castle apply` renders the
+route and reloads the gateway.
+
+## Adopting an existing Hugo site
+
+No stack needed — adopt the repo and declare how it builds:
+
+```bash
+castle program add /path/to/site --name my-site
+```
+
+Then set `build.commands` (as above) and add a `manager: caddy` deployment. This is
+how a site with a bespoke build (submodule theme + Tailwind) is wired without the
+scaffold. See @docs/registry.md.