# werkdock Agent Instructions

## Project

werkdock is a docker-like sandbox CLI over `bwrap`, with filesystem isolation only; see [README.md](README.md).
Werkator runs its CI builds and werkrevisor's reviews in werkdock sandboxes on mih09.
[docs/werkdock.werkbaum](docs/werkdock.werkbaum) holds the plan, [docs/rfcs/](docs/rfcs/) the decisions.

## Build and Test

```sh
go test ./...                              # all tests; sandbox integration tests skip without bwrap/userns
go vet ./... && gofmt -l .                 # quality gates (gofmt must print nothing)
CGO_ENABLED=0 go build -o dist/werkdock .  # one static linux binary
tools/check-licenses                       # licenses of the dependencies against tools/allowed-licenses.txt; each build
go run ./tools/vulncheck -base origin/main # only the called vulnerabilities this branch brings; each PR
go run ./tools/vulncheck                   # all called vulnerabilities; main each night
```

The checks load govulncheck and go-licenses by `go run` at a pinned version; neither becomes a dependency of the module.
Their levels come from [docs/risk-analysis.md](docs/risk-analysis.md), criticality high.
An exception from a vulnerability goes into `tools/vulnerability-exceptions.txt`, with its reason.

## Hard Invariants

- Filesystem isolation only: network, uid, `/proc`, `/dev` and `/tmp` come from the host by contract.
  This is what makes werkdock work without root on a Hostsharing Managed Webspace.
- Go, one static binary, standard library only ([RFC 0001](docs/rfcs/0001-implementation-language.md));
  a third-party dependency needs an RFC.
- Verbs and flags follow docker ([RFC 0002](docs/rfcs/0002-docker-compatible-surface.md));
  where docker and podman differ, werkdock follows podman.
  A docker flag or API endpoint that werkdock does not support fails with the reason, never silently.
- The Docker Engine API serves only endpoints measured from a real client,
  listed in [docs/testcontainers-api.md](docs/testcontainers-api.md); every other one answers 501 with the reason.
- A quirk is measured knowledge about one image version; an image that no longer matches it is refused, not guessed at.
- No imports from Werkator code and no coupling to the Werkator build; Werkator consumes the binary through `PATH`.

## Workflow

Follow [docs/agentic-workflow.md](docs/agentic-workflow.md), the workflow of all Werk repositories:
roles, steps of a PR, review rounds, PR documents, the plan, versions and the writing style.
In addition, for werkdock:

- Documents are in English.
- The version stands in `internal/cli/cli.go` (what `werkdock version` prints).
  Each PR raises it and adds a section with that version and the merge date to [CHANGELOG.md](CHANGELOG.md):
  what changed, what stays compatible, and what a consumer, Werkator first, must adapt.
  A change that consumers do not notice gets a section marked as internal.
- A decision larger than one PR is an RFC under `docs/rfcs/`.
- A merge to `main` is a release; the CI deploys nothing.
  The rollout to mih09 is manual: the new binary to `~/.werkator/bin/werkdock` of the account `mih09-werkator`,
  then a restart of the systemd user units `werkdock-api-*.service`, which otherwise keep serving the old code.