Agent runtime: majordomo in-process, Ollama Cloud config, chat endpoint (#56) (#70)

Co-authored-by: Steve Dudenhoeffer <[email protected]>

internal/agent/doc.go

@@ -1,18 +1,36 @@
-// Package agent adapts pansy's service layer to majordomo tools so an agent can
-// drive a garden in natural language ("fill the NE corner with garlic, the NW
-// with basil, the south half with beans"). Each tool runs as a fixed actor and
-// therefore inherits pansy's ACL checks for free — a viewer's fill_region returns
-// ErrForbidden, exactly as the REST API would.
+// Package agent is pansy's garden assistant: a majordomo toolbox over the
+// service layer, plus the run loop that drives a model with it.
 //
-// Two deliberate separations keep the core server lean:
+// Every tool runs as a fixed actor, so the agent inherits pansy's permission
+// checks for free — a viewer's fill_region returns ErrForbidden, exactly as the
+// REST API would. That is the whole reason the tools are thin adapters over
+// internal/service and never reach past it; the moment one does, the ACL story
+// stops being automatic and becomes something to remember.
 //
-//   - cmd/pansy does NOT import this package, so the server binary carries no
-//     agent/LLM dependencies.
-//   - the tool wiring (tools.go) sits behind the `majordomo` build tag, so the
-//     default `go build ./...` / `go test ./...` compiles without the majordomo
-//     module. Build the agent tools with `-tags majordomo` once majordomo is a
-//     dependency (`go get gitea.stevedudenhoeffer.com/steve/majordomo`).
+// # A turn is one change set
 //
-// The agent harness itself (model loop, chat surface) lives in the
-// majordomo/executus stack, outside this repo; this package is only the toolbox.
+// Runs wrap their whole turn in a single change set (source "agent"), so
+// "empty the garlic bed and plant cucumbers" — one object edit and a dozen
+// planting inserts — undoes as one action rather than thirteen. That is what
+// makes acting without a confirmation prompt defensible: the answer to "it did
+// the wrong thing" is one click, not an archaeology exercise.
+//
+// # No build tag
+//
+// This package used to sit behind a `majordomo` build tag, with cmd/pansy
+// deliberately not importing it, so the default build carried no LLM
+// dependency. Both separations are gone, on purpose: a tag that keeps the agent
+// out of the binary only earns its keep if you would ever ship a build without
+// the agent, and the agent is the point. Keeping it would have meant an
+// untagged CI that never compiled the code that matters.
+//
+// majordomo is stdlib-first and pure Go, so CGO_ENABLED=0 and the single static
+// binary survive it.
+//
+// # Unconfigured instances
+//
+// With no API key the assistant is simply not offered: the chat route isn't
+// registered and the capability isn't advertised — the same shape as OIDC
+// 404ing when unconfigured. An instance without a key starts and serves the app
+// exactly as it did before.
 package agent