chore: improve discoverability and marketing readiness

CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing to Initium
+
+Contributions are welcome! This guide covers how to build, test, and submit changes.
+
+## Prerequisites
+
+- Rust 1.88+ (stable)
+- Docker (for integration tests)
+- Helm + helm-unittest plugin (for Helm chart tests)
+
+## Build
+
+```bash
+make build
+# or directly:
+cargo build --release
+```
+
+## Test
+
+```bash
+# Unit tests
+cargo test --all-features
+
+# Clippy lints (must pass with zero warnings)
+cargo clippy --all-targets --all-features -- -D warnings
+
+# Format check
+cargo fmt -- --check
+
+# Integration tests (requires Docker)
+docker compose -f tests/docker-compose.yml up -d
+INTEGRATION=1 cargo test --all-features -- --ignored
+docker compose -f tests/docker-compose.yml down
+
+# Helm chart tests
+helm unittest charts/initium
+```
+
+## Adding a new subcommand
+
+See [docs/design.md](docs/design.md) for the architecture and step-by-step guide.
+
+In short:
+
+1. Create `src/cmd/yourcommand.rs` with a `pub fn run(log: &Logger, ...) -> Result<(), String>`
+2. Add the variant to the `Commands` enum in `src/main.rs`
+3. Wire it up in the `match cli.command` block in `main()`
+4. Add flags with `#[arg(...)]` and env var support via `env = "INITIUM_*"`
+5. Add unit tests in the same file
+6. Add integration tests in `tests/integration_test.rs`
+7. Document in `docs/usage.md` and `README.md`
+8. Update `Changelog.md` under `[Unreleased]`
+
+## Pull request expectations
+
+- All CI checks must pass (clippy, fmt, tests, helm-lint, build)
+- Include a "How to verify" section in the PR description
+- Keep diffs small and focused — separate refactors from features
+- Update docs and CHANGELOG for user-visible changes
+
+## Code style
+
+- Prefer clear code over comments
+- Propagate errors with context (`map_err(|e| format!("...: {}", e))`)
+- Use `clippy` lints and `rustfmt` defaults
+- Follow existing patterns in the codebase
+
+## Security
+
+- Never log secrets — use the redaction built into `Logger`
+- Constrain file writes to `--workdir` via `safety::validate_file_path`
+- Default to the most restrictive option
+
+## Reporting vulnerabilities
+
+See [SECURITY.md](SECURITY.md).

Cargo.toml

@@ -4,6 +4,12 @@ version = "0.1.0"
 edition = "2021"
 description = "Swiss-army toolbox for Kubernetes initContainers"
 license = "Apache-2.0"
+repository = "https://github.com/KitStream/initium"
+homepage = "https://github.com/KitStream/initium"
+documentation = "https://github.com/KitStream/initium/blob/main/docs/usage.md"
+keywords = ["kubernetes", "initcontainer", "sidecar", "container", "devops"]
+categories = ["command-line-utilities", "development-tools"]
+readme = "README.md"
 
 [[bin]]
 name = "initium"

README.md

@@ -7,6 +7,19 @@ Initium replaces fragile bash scripts in your initContainers with a single, secu
 [![CI](https://github.com/kitstream/initium/actions/workflows/ci.yml/badge.svg)](https://github.com/kitstream/initium/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 
+## Features
+
+- **Single static binary** — zero runtime dependencies, built `FROM scratch`
+- **Tiny image** — ~1.8 MB multi-arch container (amd64 + arm64)
+- **Zero CVEs** — no OS packages, no shell, no attack surface
+- **PSA `restricted` compatible** — runs as non-root (UID 65534), read-only filesystem, all capabilities dropped
+- **Sidecar mode** — `--sidecar` flag keeps the process alive for use as a Kubernetes sidecar container
+- **Structured logging** — JSON or text output with automatic secret redaction
+- **Retries with backoff** — exponential backoff, jitter, and configurable deadlines on all network operations
+- **Declarative database seeding** — YAML/JSON specs with MiniJinja templating, cross-table references, and idempotency
+- **Multi-database support** — PostgreSQL, MySQL, and SQLite drivers (optional Cargo features)
+- **Environment variable config** — all flags configurable via `INITIUM_*` env vars
+
 ## Quickstart
 
 ### Wait for Postgres before starting your app
@@ -313,6 +326,20 @@ helm install my-app charts/initium \
   --set 'initContainers[0].args[1]=tcp://postgres:5432'
 ```
 
+## Alternatives
+
+Initium was built to address limitations in existing init container tools:
+
+| Tool                                                                        | Language | Image size  | Multi-tool | Database seeding | Security posture        |
+| --------------------------------------------------------------------------- | -------- | ----------- | ---------- | ---------------- | ----------------------- |
+| **Initium**                                                                 | Rust     | ~1.8 MB     | Yes        | Yes              | PSA `restricted`, no OS |
+| [wait-for-it](https://github.com/vishnubob/wait-for-it)                    | Bash     | Needs shell | No         | No               | Requires shell + netcat |
+| [dockerize](https://github.com/jwilder/dockerize)                          | Go       | ~17 MB      | Partial    | No               | Full OS image           |
+| [k8s-wait-for](https://github.com/groundnuty/k8s-wait-for)                | Bash     | Needs shell | No         | No               | Requires shell + kubectl|
+| [wait4x](https://github.com/atkrad/wait4x)                                | Go       | ~12 MB      | No         | No               | Minimal OS              |
+
+If you only need TCP/HTTP readiness checks, any of these tools work. Initium is designed for teams that also need migrations, seeding, config rendering, and secret fetching in a single security-hardened binary.
+
 ## Documentation
 
 - [FAQ](FAQ.md) — Common questions about functionality, security, and deployment
@@ -322,7 +349,7 @@ helm install my-app charts/initium \
 
 ## Contributing
 
-Contributions are welcome! Please see the [design doc](docs/design.md) for how to add new subcommands.
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions, test commands, and PR expectations. See the [design doc](docs/design.md) for how to add new subcommands.
 
 ## License
 

charts/initium/artifacthub-repo.yml

@@ -0,0 +1,4 @@
+repositoryID: initium
+owners:
+  - name: Kitstream
+    email: opensource@kitstream.io