chmmou · chmmou · May 5, 2026 · May 5, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,97 @@
+# Contributing to kasapi-cli
+
+Thanks for your interest in contributing. This document collects the conventions a contributor needs to know on top of the in-tree references.
+
+## Before you start
+
+- This project is **not affiliated with All-Inkl.com**. The KAS-API surface is reverse-engineered from the public documentation at <https://kasapi.kasserver.com/dokumentation/phpdoc/> and from real responses captured in `testdata/`.
+- The roadmap in [README.md](README.md#roadmap) shows which endpoints are already wired up. If you want to claim an unchecked item, please open an issue first so work is not duplicated.
+- Bug reports and PRs that touch the KAS-API contract should reference the relevant doc page and, where possible, attach a redacted response fixture.
+
+## Authoritative references
+
+Read these before designing changes — do not duplicate their content into new docs:
+
+- [`AGENTS.md`](AGENTS.md) — top-level operating rules: always run `gofmt`/`goimports`, `go vet`, `golangci-lint`, `go test`; clean-architecture layering; no business logic depending on transport.
+- [`docs/go/ARCHITECTURE.md`](docs/go/ARCHITECTURE.md) — `cmd/kasapi-cli` wires; domain/use cases in `internal/<domain>/`; SOAP/HTTP/CLI are outer-layer adapters.
+- [`docs/go/STYLE_GUIDE.md`](docs/go/STYLE_GUIDE.md) — Go style.
+- [`docs/go/PATTERNS.md`](docs/go/PATTERNS.md) — recurring patterns (e.g. the per-package `Caller` interface, fixture-backed decoders, `cli.Tabular`).
+- [`docs/go/LINTING.md`](docs/go/LINTING.md) — the CI gate set.
+
+## Development setup
+
+Prerequisites:
+
+- Go (latest stable; the version pinned in `go.mod`).
+- [`golangci-lint`](https://golangci-lint.run/) matching the version used in CI.
+- A working GnuPG key — commits to `main` must be signed (the branch is protected with `required_signatures`).
+
+Standard loop:
+
+```sh
+go fmt ./...
+go vet ./...
+golangci-lint run ./...
+go test ./...
+go test -race ./...                     # for packages with concurrency
+go build ./cmd/kasapi-cli
+```
+
+## Vertical-slice pattern
+
+Each KAS endpoint is added as a single vertical slice; do not split it across modules. A new endpoint typically needs:
+
+1. **Type & decoder** in `internal/<domain>/<name>.go` — typed Go value + `Decode<Thing>` mapping the SOAP `ns2:Map` / `Array` payload, plus a per-package `Caller` interface so tests do not need network setup.
+2. **Client method** on the package's `*Client` (e.g. `(c *Client) Get(ctx, name)`).
+3. **Test** in `internal/<domain>/<name>_test.go` — fixture-backed mapping tests + a `fakeCaller` for the client method (assert the action name and any params).
+4. **Fixture** in `testdata/<domain>/<kas_action>_response_success.xml` (and `_request.xml` if useful). The fixtures are real captured responses with secrets redacted — they are the source of truth for response shape.
+5. **CLI subcommand** in `internal/cli/<domain>.go`, registered in `cmd/kasapi-cli/main.go`.
+6. **CHANGELOG entry** under `## [Unreleased] / ### Added` (or `### Fixed`, etc.). One paragraph, ending with `Closes #<issue>` if applicable.
+7. **Roadmap update** in [README.md](README.md#roadmap) — flip the corresponding `- [ ]` to `- [x]`.
+
+When the response shape differs between list and singular views (e.g. `get_domains` with vs. without `domain_name`), prefer one struct with `omitempty` on the view-specific fields rather than two structs.
+
+## Language
+
+- Commits, CHANGELOG entries, code comments, doc.go strings, and PR text are in **English**.
+- Where a file already uses ASCII fallbacks (`ae/oe/ue/ss`), keep that style consistent in the same file; otherwise use real umlauts.
+
+## Commit conventions
+
+- **[Conventional Commits](https://www.conventionalcommits.org/):** `feat:` for new features, `fix:` for bug or schema corrections, `docs:` for documentation- or CHANGELOG-only changes, `chore:` for build/tooling/repo hygiene, `test:` for test-only changes, `refactor:` for structural changes without behavior change.
+- **Signed commits.** Do not skip hooks (no `--no-verify`, no `--no-gpg-sign`). On a hook failure, fix the underlying cause and create a **new** commit — do not `--amend`.
+- **No `Co-Authored-By` trailer.** Maintainers do not use the Claude Code default trailer; please omit it as well.
+- **Selective `git add`.** Stage only files that belong to the current slice; never `git add -A` or `git add .`. Excluded by default: `.claude/`, local settings, unrelated fixtures, IDE/OS noise, secrets, captured KAS responses that have not been redacted.
+
+## Branches and pull requests
+
+```sh
+git checkout -b feature/<topic>     # new functionality
+git checkout -b fix/<topic>         # bug or schema correction
+git checkout -b docs/<topic>        # docs only
+git checkout -b chore/<topic>       # tooling / repo hygiene
+```
+
+PR body: keep it short. Summary block describing *what*, not *how*. No "Test plan" section, no generated-by footer. If an issue is open, reference it with `Closes #<n>` so the project item flips to "Done" automatically on merge.
+
+CI must be green before merge. The CI workflow runs `go fmt` (check-only), `go vet`, `golangci-lint`, and `go test` (with `-race` where applicable).
+
+`main` is protected with `required_signatures` + `enforce_admins` + `linear_history`. The GitHub UI / `gh pr merge` strips signatures and is therefore **not** used for this repo. Merging is done by the maintainer via a locally-rebased, signed fast-forward push to `main`. As a contributor you do not need to do this — you only need to keep your branch rebased on `main` and your commits signed.
+
+## Code review
+
+Findings are classified:
+
+- **Blocker** — outright wrong: bug, undefined behavior, KAS-API schema mismatch, security issue, broken invariant. Must be fixed before merge.
+- **Should** — consistency / readability / small footguns. Fix quickly if cheap; otherwise capture as a follow-up issue.
+- **Nice-to-have** — cosmetic, style, or speculative. Recorded as a grouped follow-up issue but not a merge blocker.
+
+Corrections from review land on a dedicated `fix/<topic>` branch via a separate PR; the loop ends only when no Blocker or Should-finding remains.
+
+## Reporting security issues
+
+Please do **not** open a public issue for security vulnerabilities. Contact the maintainer privately (see the commit author email or the `LICENSE` copyright holder) with a description, reproduction steps, and an assessment of impact.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the project's [BSD 3-Clause License](LICENSE).
diff --git a/README.md b/README.md
@@ -22,42 +22,23 @@
 
 ## Status
 
-Early development. No functional Go code yet — the repository currently holds documentation, agent guidance, and recorded KAS-API response fixtures used to drive offline parser tests. See the project board for the active roadmap.
+Early development. The transport, authentication, configuration, and several read modules are wired up; many write paths and the remaining read endpoints are still pending — see [ROADMAP.md](ROADMAP.md) for the current state. The repository also ships recorded KAS-API response fixtures under `testdata/` that drive offline parser tests.
 
-## What it does (planned)
+## What it does
 
-`kasapi-cli` is a command-line client for the All-Inkl KAS-API. It wraps the SOAP/`ns2:Map` wire format the API uses, handles the `KasAuth` credential-token flow (plain or session, optional 2FA), enforces the `KasFloodDelay` between calls, and exposes read and write operations for the resources documented at <https://kasapi.kasserver.com/dokumentation/phpdoc/>:
-
-- accounts, account settings, account resources
-- server information, space, space usage, traffic
-- top-level domains, domains, subdomains, DNS settings
-- mail accounts, mail forwards, mail standard filters, mailing lists
-- databases, FTP users, Samba users, DDNS users
-- cronjobs, directory protection, software install entries
-- sessions (`add_session`, `delete_session`)
-
-## Endpoints
-
-- API: <https://kasapi.kasserver.com/soap/KasApi.php>
-- Auth: <https://kasapi.kasserver.com/soap/KasAuth.php>
-
-## Configuration (planned)
-
-`kasapi-cli` reads credentials from a config file or from environment variables (`KAS_LOGIN`, `KAS_AUTHDATA`, `KAS_AUTHTYPE`). Profiles let you switch between accounts. Secrets never appear in `--help` or in default log output.
+`kasapi-cli` is a command-line client for the All-Inkl KAS-API. It wraps the SOAP/`ns2:Map` wire format the API uses, handles the `KasAuth` credential-token flow (plain or session, optional 2FA), enforces the `KasFloodDelay` between calls, and exposes read and write operations for the resources documented at <https://kasapi.kasserver.com/dokumentation/phpdoc/>.
 
 ## Building
 
-Once the Go module is bootstrapped:
-
 ```sh
 go build ./cmd/kasapi-cli
 go test ./...
 ```
 
 ## Repository layout
 
-- `cmd/kasapi-cli/` — CLI entry point (planned).
-- `internal/` — domain types, transport, mappers (planned).
+- `cmd/kasapi-cli/` — CLI entry point.
+- `internal/` — domain types, transport, mappers, CLI wiring; one package per KAS resource (see `internal/account/`, `internal/domain/`, `internal/dns/`, …) plus shared infrastructure (`internal/soap`, `internal/api`, `internal/auth`, `internal/transport`, `internal/session`, `internal/config`, `internal/cli`).
 - `testdata/` — recorded KAS-API SOAP responses; the source of truth for response shape, used by offline parser tests.
 - `docs/go/` — Go style, architecture, patterns, and linting reference for this repo.
 - `.claude/skills/kasapi-cli-git-workflow/` — git/PR/merge mechanics enforced for this project.
@@ -66,7 +47,11 @@ go test ./...
 
 ## Contributing
 
-Read `AGENTS.md` and `docs/go/ARCHITECTURE.md` before opening a PR. The git workflow (branch naming, commit style, PR shape, CI gate, signed FF-merge) is captured in `.claude/skills/kasapi-cli-git-workflow/SKILL.md`; the review-loop conventions (finding classification, re-review cycle) live next to it in `.claude/skills/kasapi-cli-code-review/SKILL.md`.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, coding conventions, the vertical-slice pattern used per KAS endpoint, the commit/PR workflow, and the code-review loop.
+
+## Roadmap
+
+The current state of the KAS-API surface — implemented vs. pending — is tracked in [ROADMAP.md](ROADMAP.md).
 
 ## License
 

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -0,0 +1,60 @@
+# Roadmap
+
+This file tracks the KAS-API surface implemented by `kasapi-cli`, grouped by domain. Checked items are wired up end-to-end (typed module + CLI subcommand + fixture-backed tests); unchecked items are still pending.
+
+The list is kept in sync with the code on `main`. To claim an unchecked item, please open an issue first so work is not duplicated — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Transport & authentication
+
+- [x] SOAP / `ns2:Map` decoder (`internal/soap`)
+- [x] `KasFloodDelay` enforcement and retry on `flood_delay` errors
+- [x] `KasAuth` credential-token flow (plain + session, optional 2FA via `--otp`)
+- [x] Persistent session-token cache (`sessions.toml`) survives across CLI invocations
+- [x] Session lifetime extension (`update_lifetime`)
+- [ ] Standalone `add_session` / `delete_session` subcommands
+
+## Configuration
+
+- [x] TOML config file with named profiles and `default_profile` selection
+- [x] Environment overrides (`KAS_LOGIN`, `KAS_AUTHDATA`, `KAS_AUTHTYPE`, `KAS_PROFILE`)
+- [x] Secrets are never echoed in `--help` or default log output
+
+## Accounts & server
+
+- [x] `account get` (`get_accounts`, `get_accountsettings`, `get_accountresources`)
+- [x] `server get` (`get_server_information`)
+
+## Usage
+
+- [x] `usage space` (`get_space`)
+- [x] `usage space-detail` (`get_space_usage`)
+- [x] `usage traffic` (`get_traffic`)
+
+## Domains, subdomains, DNS
+
+- [x] `domains list` / `domains get <name>` (`get_domains`, with `domain_name` filter)
+- [x] `subdomains list` / `subdomains get <name>` (`get_subdomains`, with `subdomain_name` filter)
+- [x] `tlds list` (`get_topleveldomains`)
+- [x] `dns list --domain <d> [--nameserver <ns>]` (`get_dns_settings`)
+- [ ] DNS write paths (`add_dns_settings`, `update_dns_settings`, `delete_dns_settings`)
+- [ ] Domain write paths (`add_domain`, `update_domain`, `delete_domain`, transfer flow)
+- [ ] Subdomain write paths (`add_subdomain`, `update_subdomain`, `move_subdomain`, `delete_subdomain`)
+
+## Mail
+
+- [ ] Mail accounts (`get_mailaccounts`, `add_mailaccount`, `update_mailaccount`, `delete_mailaccount`)
+- [ ] Mail forwards (`get_mailforwards`, `add_mailforward`, `update_mailforward`, `delete_mailforward`)
+- [ ] Mail standard filters (`get_mailstandardfilter`, `update_mailstandardfilter`)
+- [ ] Mailing lists (`get_mailinglists`, `add_mailinglist`, `update_mailinglist`, `delete_mailinglist`)
+
+## Hosting resources
+
+- [ ] Databases (`get_databases`, `add_database`, `update_database`, `delete_database`)
+- [ ] FTP users (`get_ftpusers`, `add_ftpuser`, `update_ftpuser`, `delete_ftpuser`)
+- [ ] Samba users (`get_sambausers`, `add_sambauser`, `update_sambauser`, `delete_sambauser`)
+- [ ] DDNS users (`get_ddnsusers`, `add_ddnsuser`, `update_ddnsuser`, `delete_ddnsuser`)
+- [ ] Cronjobs (`get_cronjobs`, `add_cronjob`, `update_cronjob`, `delete_cronjob`)
+- [ ] Directory protection (`get_directoryprotection`, `add_directoryprotection`, `update_directoryprotection`, `delete_directoryprotection`)
+- [ ] Software install entries (`get_softwareinstall`, `add_softwareinstall`, `delete_softwareinstall`)
+- [ ] SSL certificate management (`add_lets_encrypt_csr`, `update_ssl_certificate`, …)
+- [ ] Filesystem helpers (`chown`, `symlink`)