docs(ai): Add AGENTS.md

.github/copilot-instructions.md

@@ -0,0 +1 @@
+See AGENTS.md for agent instructions

.github/workflows/regenerate-static-assets.yml

@@ -52,7 +52,7 @@ jobs:
           ref: ${{ steps.pr.outputs.ref }}
       - name: Regenerate static assets
         run: |
-          make frontend-install-dependencies
+          make frontend-install
           make frontend-build
       - name: Commit and push changes
         id: commit

.github/workflows/test-ui.yml

@@ -14,5 +14,5 @@ jobs:
     timeout-minutes: 30
     steps:
       - uses: actions/checkout@v5
-      - run: make frontend-install-dependencies
+      - run: make frontend-install
       - run: make frontend-build

AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## Commands
+
+- `make install` — Build the `gatus` binary
+- `make run` — Run in dev mode (uses `./config.yaml`)
+- `make test` — Run all Go tests with coverage
+- `make clean` — Remove built binary
+- `make frontend-install` — Install frontend npm dependencies
+- `make frontend-build` — Build the Vue.js frontend (**must run after any `web/` changes**)
+- `make frontend-dev` — Start the Vue dev server
+
+## Key Rules
+
+- **Vendored dependencies**: After adding/updating a Go dependency, run `go mod tidy && go mod vendor`
+- **Frontend build artifacts**: `web/static/` is generated by `make frontend-build` and embedded into the Go binary at compile time via `//go:embed`. Never edit files in `web/static/` directly
+- **Config validation order**: In `config/config.go` `parseAndValidateConfigBytes`, `ValidateAlertingConfig` **must** run before `ValidateEndpointsConfig` because provider default alerts must be parsed before endpoint defaults are set
+- **Invalid configs panic at startup** — validation errors are fatal, not graceful
+- **Hot-reload**: `main.go` watches the config file and re-runs the full stop → save → load → init → start cycle. New startup logic must account for this
+
+## Environment Variables
+
+- `GATUS_CONFIG_PATH` — Config file path (default: `config/config.yaml`); can be a directory of YAML files (deep-merged)
+- `GATUS_LOG_LEVEL` — `DEBUG`, `INFO`, `WARN`, `ERROR`
+- `ENVIRONMENT=dev` — Enables CORS for frontend dev on `localhost:8081`
+
+## Project Structure
+
+- `main.go` — Entry point; loads config, initializes storage, starts watchdog + API server
+- `config/` — Central config struct (`config.go`) and sub-packages per config section (each with `ValidateAndSetDefaults()`)
+- `alerting/` — Alerting config (`config.go`), alert types (`alert/type.go`), and one sub-package per provider under `provider/`
+- `api/` — Fiber-based HTTP API routes and SPA serving
+- `watchdog/` — Monitoring loop; spawns a goroutine per endpoint with semaphore-based concurrency control
+- `client/` — HTTP/gRPC client used for health checks
+- `storage/store/` — Storage abstraction with `memory/`, `sql/` (SQLite + PostgreSQL) implementations
+- `security/` — Authentication (basic + OIDC) and security middleware
+- `web/app/` — Vue 3 frontend source; builds to `web/static/` (embedded into the Go binary)
+- `vendor/` — Vendored Go dependencies (committed to repo)
+
+## Common Changes
+
+### Adding an Alerting Provider
+
+Use `alerting/provider/slack/` as the reference implementation. Every new provider touches **6 locations**:
+
+1. **Create provider package** — `alerting/provider/{name}/{name}.go` + `{name}_test.go`
+   - `Config` struct with `Validate()` and `Merge(*Config)` methods
+   - `AlertProvider` struct with `DefaultConfig` (yaml inline), `DefaultAlert *alert.Alert`, `Overrides []Override`
+   - Use `client.GetHTTPClient(nil)` (not `http.DefaultClient`), always `defer response.Body.Close()`
+2. **Register type** — Add `Type{Name} Type = "{name}"` in `alerting/alert/type.go`
+3. **Add to config struct** — Add field to `alerting.Config` in `alerting/config.go`; the **YAML tag must exactly match** the `alert.Type` string (reflection-based lookup via `GetAlertingProviderByAlertType`)
+4. **Add compile-time checks** — Both `_ AlertProvider = (*pkg.AlertProvider)(nil)` **and** `_ Config[pkg.Config] = (*pkg.Config)(nil)` in `alerting/provider/provider.go`
+5. **Register in validation** — Add the type to the `alertTypes` slice in `config/config.go` `ValidateAlertingConfig`
+6. **Document** — Add to README.md in alphabetical order
+
+### Adding a Config Section
+
+1. Create package in `config/` with struct + `ValidateAndSetDefaults()` method
+2. Add field to `Config` struct in `config/config.go`
+3. Add `Validate*` call in `parseAndValidateConfigBytes` — **respect ordering constraints** (see comments in that function)
+
+## Frontend
+
+- Vue 3 Composition API (`<script setup>`) + Tailwind CSS
+- Props-based data flow — **do not use provide/inject**
+- All components must include `dark:` prefixed Tailwind classes for dark mode
+- `window.config` contains server-injected UI settings (Go template placeholders)
+
+## API Routes (`api/api.go`)
+
+- Unprotected routes are registered **before** `ApplySecurityMiddleware`
+- Protected routes are registered **after** — placement order matters
+
+## Testing
+
+- Config structs should have `*_test.go` files
+- Use `t.Parallel()` where appropriate
+- API tests spin up test servers (see existing `*_test.go` in `api/`)
+
+## Commits & PRs
+
+When creating a commit or PR as an agent, state that it was made by an agent and include your model name and version.

Makefile

@@ -25,12 +25,15 @@ test:
 # Docker #
 ##########
 
+.PHONY: docker-build
 docker-build:
 	docker build -t twinproduction/gatus:latest .
 
+.PHONY: docker-run
 docker-run:
 	docker run -p 8080:8080 --name gatus twinproduction/gatus:latest
 
+.PHONY: docker-build-and-run
 docker-build-and-run: docker-build docker-run
 
 
@@ -38,11 +41,14 @@ docker-build-and-run: docker-build docker-run
 # Front end #
 #############
 
-frontend-install-dependencies:
+.PHONY: frontend-install
+frontend-install:
 	npm --prefix web/app install
 
+.PHONY: frontend-build
 frontend-build:
 	npm --prefix web/app run build
 
-frontend-run:
+.PHONY: frontend-dev
+frontend-dev:
 	npm --prefix web/app run serve