--- title: Agent Guidance last_modified: 2026-08-22 --- This file is the single source of guidance for any automated agent working in this repository. There is no other agent-facing file, and none is to be created: no vendor-named directory and no vendor-named markdown file is ever committed. Keeping such directories out of commits is what `.gitignore` is for, and listing them there is correct — an ignore entry is plumbing, not documentation. What must not appear is vendor-named _content_: committed configuration, instructions or notes addressed to one particular tool. Guidance goes here instead, written so that any agent can follow it. Nothing in this repository names an assistant, model or vendor in its prose. That rule propagates: every project seeded from this template inherits it. Read `docs/REPO_POLICIES.md` as well. Where this file and that one overlap, they agree; where this file is silent, that one governs. ## What this repository is A template. It is a working HTTP service — it builds, tests, lints and runs — whose purpose is to be copied. Nothing in it is precious. The `widgets` table, the index page and the debug panic route are there to prove the machinery works end to end, and are meant to be deleted. ## Iron rules These are not preferences. A change that breaks one of them is wrong regardless of what else it achieves. 1. **Never mention any assistant, model, vendor, or the involvement of automated assistance** — not in code, comments, documentation, commit messages, PR bodies, or trailers. No `Co-Authored-By`, no session links, no attribution of any kind. 2. **Linting runs in Docker, never on the host.** `script/lint` builds `Dockerfile.lint` against a digest-pinned image. Do not install `golangci-lint` locally and do not run it directly. 3. **Never run `go build`, `go test`, `go vet`, `gofmt` or `golangci-lint` directly.** Use the `make` targets or the `script/` entrypoints. They carry the flags and policies (`-count=1`, `-race`, timeouts, docker-only linting) that a raw invocation silently bypasses. This applies to mid-task checks, not just the final one. 4. **Configuration that is set but unparseable aborts startup.** A default applies only to a value that is ABSENT. Silently substituting a default for a value the operator got wrong turns their mistake into a misconfiguration that surfaces much later, somewhere else. See `internal/config`. Reject any change that weakens this. 5. **Never use scripted search-and-replace to edit files** — no `sed -i`, `perl -pi`, `awk` rewrites, or scripted heredocs. Read the file and edit it, even when there are many similar edits. The single exception is `script/rename`, which is a tool an operator runs once, against a known-shaped tree, at seed time — and which deletes itself afterwards. 6. **Formatting only via `make fmt`.** Never hand-roll a reformat. `make fmt-check` is the read-only form and must stay non-mutating. 7. **Pin every external reference by hash.** Docker base images by `@sha256:`, Actions by commit SHA, Go modules by `go.sum`. A version tag is server-mutable and therefore remote code execution. 8. **Clean up every container and image you create. Never run `docker builder prune`, `docker image prune`, or any other prune.** Shared infrastructure purges on its own schedule; a prune destroys other people's work in progress. 9. **Write verbatim identifiers in backticks in markdown** — branch names, filenames, commands, environment variables. This is what distinguishes a branch literally named `next` from the word "none" meaning no such branch exists. ## Entrypoints Everything is a `script/` entrypoint with a thin `make` shim. The scripts are the real interface; `make` exists because fingers know it. See the Entrypoints section of `README.md` for what each one does. The two that matter most: - `make check` — `test` + `lint` + `fmt-check`. Never modifies files. This is the gate for a commit. - `script/cibuild` — the container build with the lint and test stages cache-busted, plus assertions that they really ran and really saw the whole repository. This is the gate for a push, and the Gitea workflow runs it. A green `docker build` on its own proves nothing: an unchanged tree serves every layer from cache and exits 0 having executed nothing, and a `.dockerignore` entry can hide a package from a linter that then truthfully reports `0 issues.` over what is left. `script/assert-step-ran` and `script/assert-context-complete` exist to close both holes, and their comments explain what they still cannot see. Do not weaken them. ## Branching model - `main` is the default branch and is kept green. - Work happens on a branch off `main`. - Merge to `main` directly when the branch is not protected; otherwise open a PR. - `docs/TODO.md` changes go in the same commit as the work they describe. - Push finished work to the remote. Work that exists only locally is treated as lost. - Never force-push, and never rewrite published history. ## Layout ``` cmd/simplexcalc/ cobra command tree; main() and serve internal/app/ the fx object graph — the only place that knows which concrete type satisfies what internal/config/ viper-backed configuration; the abort-on-garbage rule internal/database/ sqlite handle, embedded schema, migration runner internal/globals/ build-time metadata (ldflags) internal/handlers/ HTTP handlers, one struct, fx-injected dependencies internal/logger/ log/slog, JSON always internal/middleware/ request id, logging, metrics, recovery, timeout, body cap, security headers, CSRF internal/render/ template compilation and execution internal/server/ lifecycle, route table, static file serving internal/telemetry/ Sentry and Prometheus templates/ go:embed HTML: base document, pages, partials static/ go:embed CSS and JS script/ the entrypoints ``` ## Conventions - **Dependency injection through `fx`.** A constructor takes an `fx.Lifecycle` and a `Params` struct; it never reaches for a package-level singleton. Returning an error from a constructor aborts startup, which is how configuration failures become refusals to start. - **Logging is `log/slog` only.** Never `zerolog`, never `logrus`. JSON output in every environment. `net/http`'s own error output is routed through the same handler so that one process emits one format. - **Errors wrap with `%w`** and are compared with `errors.Is`. Sentinel errors are package-level `var`s named `errThing`. - **A handler never shows an error's text to a client.** The client gets a chosen message; the error goes to the log and to Sentry, joined by the request id that is also in the response header. - **Route labels in metrics are chi route PATTERNS, never paths.** Labelling by path makes every distinct URL a new time series, and a crawler then owns the process's memory. - **Tests exercise behaviour, not implementation.** The server tests start a real listener against a real database and speak HTTP to it. Prefer that over asserting on internals. - **Comments explain why, and traps.** Delete the history, the reasoning-out-loud and the self-justification; keep what a reader needs in order not to fall in. ## What to change when seeding a new project 1. Clone, then run `script/rename [module-path]` on a clean tree. It rewrites the placeholder name and module path everywhere, renames `cmd/simplexcalc`, and deletes itself. Review the diff. 2. Delete the example domain: `internal/database/schema/001_widgets.sql`, `internal/database/model_widget.go`, the widget parts of `internal/handlers/index.go` and `templates/index.html`, and their tests. Start your own schema at `001`. 3. Rewrite `README.md` for the new project. It currently describes the template, which the new project is not. 4. Rewrite this file's "What this repository is" section, and delete this list. Keep the iron rules, the entrypoints, the branching model and the conventions — they are why the template exists. 5. Reset `docs/TODO.md`: keep the Workflow section, replace the rest. 6. Decide on `CSRF_KEY` and the metrics credentials before the first deployment. See `README.md` for what each one does when unset.