v0.2.1: arg validation, RDAP banner fix, demo gif

.gitignore

@@ -18,3 +18,6 @@
 # Test
 *.test
 coverage.out
+
+# Local release-notes drafts (fed to `gh release create --notes-file`)
+/release-notes.md

.markdownlint.jsonc

@@ -0,0 +1,19 @@
+{
+  "default": true,
+  "MD013": {
+    "line_length": 85,
+    "heading_line_length": 85,
+    "code_blocks": false,
+    "tables": false,
+    "stern": true
+  },
+  "MD033": false,
+  "MD041": false,
+  "MD060": false,
+  "ignores": [
+    ".github/**",
+    "vendor/**",
+    "node_modules/**",
+    "release-notes.md"
+  ]
+}

CODE_OF_CONDUCT.md

@@ -41,5 +41,5 @@ an individual is officially representing the project in public spaces.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/),
-version 2.0.
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org/), version 2.0.

CONTRIBUTING.md

@@ -1,18 +1,21 @@
 # Contributing to dibs
 
-Thanks for your interest in contributing to dibs! This document provides guidelines and information for contributors.
+Thanks for your interest in contributing to dibs! This document provides
+guidelines and information for contributors.
 
 ## Code of Conduct
 
-By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
+By participating in this project, you agree to abide by our
+[Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## How to Contribute
 
 ### Reporting Bugs
 
 Before submitting a bug report:
 
-1. Check the [existing issues](https://github.com/sitapix/dibs/issues) to avoid duplicates
+1. Check the [existing issues](https://github.com/sitapix/dibs/issues) to avoid
+   duplicates
 2. Make sure you're using the latest version
 
 When submitting a bug report, include:
@@ -60,12 +63,15 @@ Requires Go 1.26+.
 
 ### Git hooks (opt-in)
 
-Hooks live in `.githooks/` and are only active after you run `make setup`, which points `core.hooksPath` at that directory. The hooks are advisory:
+Hooks live in `.githooks/` and are only active after you run `make setup`,
+which points `core.hooksPath` at that directory. The hooks are advisory:
 
 - **pre-commit** runs `gofmt`, `go vet`, and (if installed) `golangci-lint`
 - **pre-push** runs `go build`, `go mod verify`, and `go test -race -short ./...`
 
-If you already use another hook manager (lefthook, pre-commit.com, husky, a global hooks directory), `make setup` will print a warning and show you how to restore your previous `core.hooksPath` before overriding it.
+If you already use another hook manager (lefthook, pre-commit.com, husky, a
+global hooks directory), `make setup` will print a warning and show you how to
+restore your previous `core.hooksPath` before overriding it.
 
 Bypass the hooks for a WIP commit or an emergency fix:
 
@@ -74,15 +80,19 @@ git commit --no-verify
 git push --no-verify
 ```
 
-Use sparingly — the pre-release gate (`make release-check`) re-runs everything the hooks check plus more, so anything the hooks would have caught will still block a tag.
+Use sparingly. The pre-release gate (`make release-check`) re-runs everything
+the hooks check plus more, so anything the hooks would have caught will still
+block a tag.
 
 ## Coding Standards
 
 - Follow standard Go conventions (`gofmt`, `go vet`)
 - Keep functions focused and small
 - Handle errors explicitly; don't ignore them
 - Add tests for new functionality
-- Minimize external dependencies. dibs uses only the Go standard library plus `golang.org/x/net` (for the Public Suffix List); justify any new dependency in the PR description
+- Minimize external dependencies. dibs uses only the Go standard library plus
+  `golang.org/x/net` (for the Public Suffix List); justify any new dependency
+  in the PR description
 
 ### Commit Messages
 
@@ -92,7 +102,8 @@ Use sparingly — the pre-release gate (`make release-check`) re-runs everything
 - Reference issues when applicable: "Fix DNS timeout (#123)"
 
 Example:
-```
+
+```text
 Add CSV output format option
 
 - Implement --csv flag for spreadsheet-compatible output
@@ -126,14 +137,34 @@ Before tagging a release, run the full pre-flight gate:
 # Requires: go install golang.org/x/tools/cmd/deadcode@latest
 #           go install golang.org/x/vuln/cmd/govulncheck@latest
 #           golangci-lint (https://golangci-lint.run/usage/install/)
+#           brew install markdownlint-cli2
 make release-check
 ```
 
-`release-check` is a strict superset of the pre-commit and pre-push hooks: `gofmt`, `go vet`, `golangci-lint`, full race test suite (not `-short`), deadcode detection, govulncheck, a `go mod tidy -diff` drift check (non-mutating), and a reproducibility build that verifies the release ldflags still wire `main.version` correctly. Requires network access. Don't push a tag until it passes.
+`release-check` is a strict superset of the pre-commit and pre-push hooks:
+`gofmt`, `go vet`, `golangci-lint`, full race test suite (not `-short`),
+deadcode detection, govulncheck, a `go mod tidy -diff` drift check
+(non-mutating), and a reproducibility build that verifies the release ldflags
+still wire `main.version` correctly. Requires network access. Don't push a tag
+until it passes.
 
-## Project Structure
+## Regenerating the demo GIF
 
+The README demo (`demo/demo.gif`) is scripted with
+[vhs](https://github.com/charmbracelet/vhs). To update it:
+
+```bash
+brew install vhs      # one-time
+make build            # produce ./dibs
+vhs demo/demo.tape    # writes demo/demo.gif
 ```
+
+Edit `demo/demo.tape` to change what's shown, then re-render and commit both
+the tape and the resulting GIF.
+
+## Project Structure
+
+```text
 dibs/
 ├── main.go            # CLI entry point and orchestration
 ├── fetch.go           # TLD list and RDAP bootstrap fetching/caching
@@ -143,6 +174,7 @@ dibs/
 ├── output/            # Terminal, JSON, CSV renderers
 ├── rdap/              # RDAP verification client
 ├── tlds/              # TLD list parsing, caching, filtering
+├── demo/              # vhs tape and rendered GIF for the README
 ├── Formula/           # Homebrew formula
 ├── .github/workflows/ # CI and release automation
 ├── install.sh         # Binary installer script
@@ -158,7 +190,8 @@ Releases are managed by maintainers. The process:
 
 1. Create a git tag: `git tag -a v1.x.x -m "Release v1.x.x"`
 2. Push tag: `git push origin v1.x.x`
-4. CI automatically builds binaries, creates a GitHub release, and updates the Homebrew formula
+3. CI automatically builds binaries, creates a GitHub release, and updates the
+   Homebrew formula
 
 ## Questions?
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build test clean lint setup install fmt coverage release-check
+.PHONY: build test clean lint docs-lint setup install fmt coverage release-check
 
 VERSION ?= dev
 
@@ -15,6 +15,10 @@ lint:
 	go vet ./...
 	golangci-lint run ./...
 
+docs-lint:
+	@command -v markdownlint-cli2 >/dev/null || { echo "install: brew install markdownlint-cli2"; exit 1; }
+	markdownlint-cli2 "**/*.md" "!.github/**" "!release-notes.md" "!vendor/**"
+
 setup:
 	@prev=$$(git config --get core.hooksPath || true); \
 	  if [ -n "$$prev" ] && [ "$$prev" != ".githooks" ]; then \
@@ -47,6 +51,9 @@ release-check:
 	@echo "→ golangci-lint"
 	@command -v golangci-lint >/dev/null || { echo "install: https://golangci-lint.run/usage/install/"; exit 1; }
 	@golangci-lint run ./...
+	@echo "→ markdownlint"
+	@command -v markdownlint-cli2 >/dev/null || { echo "install: brew install markdownlint-cli2"; exit 1; }
+	@markdownlint-cli2 "**/*.md" "!.github/**" "!release-notes.md" "!vendor/**"
 	@echo "→ go test -race (full)"
 	@go test -race -count=1 ./...
 	@echo "→ deadcode"