Add vctl and vctx Vault token CLIs

Introduces the vault-tools monorepo: two Go CLIs that share a config file
(~/.config/vault) and token cache (~/.cache/vault) for working with multiple
Vault instances (contexts).

- add shared/ library: config parsing (vctl.yaml/config.yaml, per-context
  overrides, slash contexts), token cache (0600/0700, atomic writes, path-
  traversal guards), and a small hand-rolled Vault HTTP client (login/renew)
- add vctl: login/renew (single or --all), list, --method/--user overrides,
  no-echo password/token prompts, dynamic context completion
- add vctx: resolve a context, set VAULT_ADDR/VAULT_TOKEN/VAULT_NAMESPACE and
  exec the vault CLI, passing remaining args through untouched
- add unit tests across shared/, vctl and vctx command layers (config
  resolution, cache paths, vault client, --all iteration + error aggregation,
  vctx arg pass-through and env construction via fakeable exec/prompt seams)
- add Makefile (build/test/completions/rpm, patch|minor|major version bumps),
  nfpm RPM packaging bundling bash/zsh/fish completions for both binaries
- add Woodpecker pipelines: build/test/pre-commit on PRs, and a tag release
  that cross-compiles, builds+uploads the RPM to artifactapi, and cuts a Gitea
  release (serviceAccountName default, k8s resources on every step)
- add README, per-command docs (docs/vctl.md, docs/vctx.md), AGENTS.md and an
  example config

Claude-Session: https://claude.ai/code/session_015ur3i7D2azsMAWTSVABApv

README.md

@@ -1,3 +1,100 @@
 # vault-tools
 
-Monorepo of Go CLI tools for managing Vault tokens across multiple vault instances: vctl (login/renew per-context tokens) and vctx (context-aware wrapper around the vault CLI).
+A Go monorepo of small CLI tools for working with multiple Vault instances
+("contexts"). Both tools share a single config file (`~/.config/vault/`) and
+token cache (`~/.cache/vault/`), so once a context is configured every tool
+knows about it.
+
+| Tool                 | Purpose                                                                 |
+| -------------------- | ----------------------------------------------------------------------- |
+| [`vctl`](docs/vctl.md) | Log in to / renew Vault tokens per context and cache them on disk.    |
+| [`vctx`](docs/vctx.md) | Run the real `vault` CLI against a named context (sets `VAULT_ADDR`/`VAULT_TOKEN`/`VAULT_NAMESPACE`, then execs `vault`). |
+
+See the per-command docs in [`docs/`](docs/) for full details.
+
+## Quick start
+
+```bash
+# 1. Configure your vaults
+mkdir -p ~/.config/vault
+cat > ~/.config/vault/vctl.yaml <<'YAML'
+defaults:
+  method: ldap
+  user: ben
+contexts:
+  sydney:
+    address: https://vault.syd1.au.unkin.net
+  staging/sydney:
+    address: https://vault-staging.syd1.au.unkin.net
+    namespace: staging
+YAML
+
+# 2. Log in (prompts for password), caches a token under ~/.cache/vault/
+vctl login sydney
+vctl login --all          # or log in to every context at once
+
+# 3. Use the vault CLI against a context
+vctx --context sydney kv put kv/foo/bar secret=baz
+vctx --context staging/sydney kv list kv/
+
+# 4. Keep tokens fresh
+vctl renew --all
+
+# See what's configured and which tokens are still valid
+vctl list
+```
+
+## Configuration
+
+Both tools read the first of `~/.config/vault/vctl.yaml` or
+`~/.config/vault/config.yaml` that exists (`$XDG_CONFIG_HOME` honoured). The
+file maps context names to a vault address plus optional per-context overrides
+(`method`, `user`, `namespace`, `path`) with file-level `defaults`. Context
+names may contain slashes, which nest on disk in the token cache. See
+[docs/vctl.md](docs/vctl.md#configuration) for the full schema and resolution
+rules.
+
+Tokens are cached under `~/.cache/vault/<context>` (`$XDG_CACHE_HOME` honoured)
+as JSON with restrictive permissions (files `0600`, dirs `0700`), storing the
+token plus its accessor, policies, TTL/expiry and renewable flag.
+
+## Layout
+
+```
+shared/            # config parsing, token cache, Vault HTTP client (shared lib + tests)
+vctl/              # vctl CLI (main package)
+vctx/              # vctx CLI (main package)
+docs/              # per-command documentation
+packaging/nfpm.yaml# nfpm spec (envsubst-templated) for the RPM (both binaries + completions)
+scripts/build-rpm.sh
+.woodpecker/       # CI: build, test, pre-commit (PR) + release (tag)
+Makefile           # build / test / completions / rpm / version-bump targets
+```
+
+## Building
+
+```bash
+make build          # build vctl + vctx into dist/
+make test           # go test -race ./...
+make completions    # generate bash/zsh/fish completions into dist/completions/
+make rpm            # build + package an RPM (needs nfpm)
+```
+
+## Releasing
+
+Releases run in Woodpecker on a `v*` tag. Bump and tag with:
+
+```bash
+make patch   # or: make minor / make major
+```
+
+which creates the next semver tag and pushes it. The release pipeline then
+tests, cross-compiles both binaries (linux/darwin × amd64/arm64), builds an RPM
+(bundling shell completions), PUTs the RPM to the artifactapi local `rpm-internal`
+yum repo, and cuts a Gitea release with the binaries + checksums attached.
+
+## Installation
+
+Install the RPM from the internal yum repo (ships both binaries plus
+bash/zsh/fish completions), or grab a prebuilt binary from the Gitea release
+assets.