# AGENTS.md

CLI for Schlundtech DNS. Go, cobra. Read `README.md` first — it is the source of truth for what the tool does.

## Rules

- **Docs and code must never contradict.** Every command in `README.md` must exist, with the flags and output described. If you change the CLI, update `README.md` in the same change. Verify with `go run . <command> --help`.
- **Go only.** No other language, no script substitutes.
- **gopls is the diagnostic source of truth.** Do not guess at type errors. Run `gopls check <file>` (or `gopls definition` / `gopls references` when you need to navigate). Fix what gopls reports; do not suppress.
- **cobra for the CLI.** One command per file under `cmd/`. Every command needs `Short`, `Long`, and a complete `Example` in its help text. No hand-rolled flag parsing.
- **Errors go to stderr, data goes to stdout.** Anything pipeable must not be polluted by log output.
- **Never log or echo credentials.**

## Layout

```
main.go          entrypoint
cmd/             one cobra command per file
internal/        packages; api/ holds the gateway client
```

`internal/api` is the only place that speaks HTTP to the gateway. Commands must not build requests themselves.

## Workflow

```bash
go build ./...
go test ./...
gopls check ./...        # must be clean before you stop
```

## Credentials

Read from the environment (`SCHLUNDTECH_USER`, `SCHLUNDTECH_PASSWORD`, `SCHLUNDTECH_CONTEXT`) or a config file. Never commit them. Writes to DNS are public and propagate immediately — every mutating command needs a `--dry-run` flag.

## Generated files

`.opencode/skill/`, `.opencode/agent/`, `.opencode/command/` are generated from the `maister` submodule. Never edit them; run `node tools/build-maister-opencode.mjs` and `node tools/verify-maister-opencode.mjs` after `git -C maister pull`.

## References

- **The gateway is AutoDNS.** `gateway.schlundtech.de` is Schlundtech's hostname
  for InterNetX's AutoDNS platform — same host as `gateway.autodns.com` (the IP
  reverse-resolves to it). Use `gateway.schlundtech.de` as the default endpoint.
- **XML is the transport.** Schlundtech's own web portal is also built on the
  AutoDNS **JSON** API (`cloud.schlundtech.com/services/backend/zone/...` returns
  the documented `stid`/`status`/`object`/`data` envelope with the same task
  codes: S0205 zone inquire, S0210 axfr, S0225 zone list). Do not mistake that
  for a public API: it authenticates by **portal session cookie only** — no
  BasicAuth — so it is the frontend's private backend, versioned with
  Schlundtech's release cycle, and unusable without driving a browser login
  plus 2FA. `api.autodns.com/v1` is the documented JSON API but rejects a
  Schlundtech login with `EF1322002 "Application could not be found."`: the
  BasicAuth username must be a registered *application* on InterNetX's side
  (`x-autodns-agent: PHOENIX` does not change this). Build against the XML
  gateway, which takes the credentials a Schlundtech customer actually has.
- **Context ID is `10`.** Verified against the real account: zone responses
  carry `"owner":{"context":10,"user":"<id>"}`.
- **The XML gateway answers HTTP 200 even on failure.** Verified: a request with
  bad credentials returns `HTTP 200` and this body:
  `response/result/msg/{code:EF00202, text:"User does not exist or password
  incorrect.", object:{type:user, value:<user>}}`, with the sibling
  `status/{code:E00000, type:error}` staying generic. **Never branch on the HTTP
  status code** — parse the body, treat `result/msg/code` as the real error and
  `result/status/type` as the success flag. Non-2xx from this host is an nginx
  404 (wrong path), never an application error. Whether the 3 req/s limit comes
  back as an HTTP 429 or as an in-body error is still unverified.
- Zone read = task `0205`. Record replace = task `0202001` (`rr_rem` + `rr_add`
  in one transaction, `system_ns` required). Zone's own NS is the first NS in
  `nameServers` (a.k.a. `virtualNameServer`).
- Record shape is `{name, type, value}` plus `ttl`, where the apex is the empty
  name. `nameServers` is the NS set. Task `0210` returns a plain zone file.
- Working implementations: https://github.com/jurica/ddns-schlundtech (Go), https://github.com/couchtyp/certbot-dns-schlundtech, https://github.com/wosc/schlund-ddns