docs: backfill architecture decision records for earlier decisions

CONTRIBUTING.md

@@ -12,6 +12,14 @@ gofmt -l .   # should print nothing
 CI runs `gofmt`, `go vet`, `go mod tidy` verification, and `go test -race`, so
 run them locally before opening a pull request.
 
+## Architecture decisions
+
+Design decisions are recorded as ADRs in [`docs/adr/`](docs/adr/). Read them
+before changing how `kir` is structured or behaves — they explain why the
+current design is the way it is. If a change revisits a decision, update or
+supersede the relevant ADR in the same pull request; add a new ADR for a new
+decision. This applies to human and AI contributors alike.
+
 ## Commit messages
 
 This project uses [Conventional Commits](https://www.conventionalcommits.org).

docs/adr/0001-typed-kubernetes-decoding.md

@@ -0,0 +1,13 @@
+# 1. Extract images by decoding manifests with the typed Kubernetes scheme
+
+- Status: accepted — **under reconsideration (#26)**
+- Date: 2025-03-13 _(recorded retrospectively 2026-08-08)_
+
+Decode each document with the typed client-go scheme and read the PodSpec via a
+type switch over a fixed set of workload kinds (`Pod`, `Deployment`, `DaemonSet`,
+`ReplicaSet`, `StatefulSet`, `Job`, `CronJob`). Anything else yields no images.
+
+Precise and dependency-light, but only the hardcoded kinds are understood:
+custom resources that embed a PodSpec (Argo Rollouts, Knative, …) are silently
+missed. #26 proposes finding the PodSpec structurally instead (Cue in #27–#30)
+and #75 catalogs what's missed — hence "under reconsideration".

docs/adr/0002-cli-input-model.md

@@ -0,0 +1,11 @@
+# 2. Take manifest sources as positional arguments, with `-` for stdin
+
+- Status: accepted
+- Date: 2025-03-13 _(recorded retrospectively 2026-08-08)_
+
+Manifest sources are positional arguments — each a file, a directory (expanded),
+or a shell glob; a single `-` reads a stream from stdin. No input flags.
+
+Composes with the shell (`kir manifests/*.yaml`, `kubectl get … -o yaml | kir -`)
+and follows the Unix filter convention. `-` is an overloaded sentinel, so
+argument resolution (`fileutil`) special-cases it against real paths.

docs/adr/0003-package-layout.md

@@ -0,0 +1,11 @@
+# 3. Layer the code as cmd → processor → yamlparser → k8s
+
+- Status: accepted
+- Date: 2025-03-17 _(recorded retrospectively 2026-08-08)_
+
+One-directional flow `main → cmd → processor → yamlparser → k8s`, with `fileutil`
+for argument/glob resolution: `cmd` wires the CLI, `processor` orchestrates per
+source, `yamlparser` decodes documents, `k8s` pulls the PodSpec and images.
+
+Each layer is unit-testable in isolation and new behavior has an obvious home, at
+the cost of more packages than a tool this size strictly needs.

docs/adr/0004-approval-testing.md

@@ -0,0 +1,13 @@
+# 4. Pin behaviour with golden (approval) tests
+
+- Status: accepted
+- Date: 2025-03-18 _(recorded retrospectively 2026-08-08)_
+
+Use [`go-approval-tests`](https://github.com/approvals/go-approval-tests): run
+real manifests through `kir` and compare output against committed
+`*.approved.txt` goldens (replacing an informal `examples/` dir). Later refined
+to capture stdout, stderr, and the exit code separately through one seam
+(ADR 0005).
+
+Adding a case is cheap (drop a manifest, approve output) and the goldens double
+as documentation; intentional output changes require an explicit approve step.

docs/adr/0005-run-entry-point-seam.md

@@ -0,0 +1,12 @@
+# 5. Expose the CLI as an in-process `Run(args, stdin, stdout, stderr) int`
+
+- Status: accepted
+- Date: 2026-08-02 _(recorded retrospectively 2026-08-08)_
+
+The whole CLI is one function `Run(args []string, stdin io.Reader, stdout, stderr
+io.Writer) int` — no `os.Exit`, no global streams. `main.go` only wires the real
+`os` values and calls `os.Exit(Run(...))`; golden tests (ADR 0004) call `Run` and
+capture the (stdout, stderr, exit code) triple.
+
+The full CLI contract is exercised in-process; every path threads the four
+parameters instead of reaching for globals.

docs/adr/0006-conventional-commits-and-releases.md

@@ -0,0 +1,14 @@
+# 6. Automate releases from Conventional Commits
+
+- Status: accepted
+- Date: 2026-08-06 _(recorded retrospectively 2026-08-08)_
+
+Commit messages and PR titles follow
+[Conventional Commits](https://www.conventionalcommits.org/). release-please
+derives the version and `CHANGELOG.md` from commit types on `master`; GoReleaser
+builds and publishes artifacts. `fix:`/`perf:` → patch, `feat:` → minor,
+`feat!:`/`BREAKING CHANGE:` → major; `ci|build|docs|refactor|test|chore` → none.
+Renovate emits `fix(deps):`/`ci(deps):`.
+
+No manual release steps, but a mistyped type mis-classifies a release, and
+squash-merges make the PR title load-bearing.

docs/adr/README.md

@@ -0,0 +1,18 @@
+# Architecture Decision Records
+
+Short records of the significant architectural decisions in `kir`, in the order
+they were made. See Michael Nygard's
+[Documenting architecture decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
+for the format.
+
+ADRs 0001–0006 were recorded retrospectively (on 2026-08-08); each carries the
+date the decision was actually made.
+
+| ADR | Decision | Date |
+| --- | --- | --- |
+| [0001](0001-typed-kubernetes-decoding.md) | Extract images by decoding manifests with the typed Kubernetes scheme (under reconsideration — #26) | 2025-03-13 |
+| [0002](0002-cli-input-model.md) | Take manifest sources as positional arguments, with `-` for stdin | 2025-03-13 |
+| [0003](0003-package-layout.md) | Layer the code as cmd → processor → yamlparser → k8s | 2025-03-17 |
+| [0004](0004-approval-testing.md) | Pin behaviour with golden (approval) tests | 2025-03-18 |
+| [0005](0005-run-entry-point-seam.md) | Expose the CLI as an in-process `Run(args, stdin, stdout, stderr) int` | 2026-08-02 |
+| [0006](0006-conventional-commits-and-releases.md) | Automate releases from Conventional Commits | 2026-08-06 |