Contributing to 4got

Dev environment setup

1. Clone the repo and cd into it.
2. Install Go 1.25+ (the go.mod requires 1.25.0).
3. Build: cd go-server && CGO_ENABLED=1 go build -o 4got .
4. Copy data/config.default.kdl to data/config.kdl and set your owner-secret.
5. Run: cd .. && go-server/4got

CGO is required for the SQLite driver.

Adding a new KDL engine

Generic engines are defined in data/engines.kdl and parsed by go-server/generic_engine.go. See engine-spec.md for the full KDL schema. The fastest workflow is the admin playground at /admin/engines/new (owner-only): fill in the form, test against a live query, then click “Save Engine” to append the KDL block to disk and register it without a restart.

Adding a new oracle

Oracles are instant-answer widgets shown above search results (calculator, unit converter, currency, etc.).

1. Write your oracle function in go-server/oracles_extra.go. Follow the existing pattern: the function takes a query string (and optionally *http.Request, http.ResponseWriter, Config) and returns *OracleAnswer or nil.
2. Register it in go-server/oracles.go inside CheckOracles(). Add a call to your function in the appropriate section (local oracles, API oracles, or knowledge oracles). Order matters: the first match in the local oracle section wins.

Running tests

cd go-server && CGO_ENABLED=1 go test ./...

Code style

• No comments unless the WHY is non-obvious. Do not explain what the code does if it is clear from reading it.
• AI-generated files get a header: // AI-generated: <model>
• Keep functions short. If a function needs a comment block explaining it, it should probably be smaller.

PR expectations

• CGO_ENABLED=1 go build -o /dev/null . must pass.
• go vet ./... must be clean.
• Do not introduce new linter warnings.