diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
new file mode 100644
index 0000000..2ca9e9a
--- /dev/null
+++ b/docs/CONTRIBUTING.md
@@ -0,0 +1,88 @@
+# Contributing to Railiance
+
+Welcome, and thank you for contributing!  
+Railiance is an opinionated Infrastructure-as-Code framework.  
+To keep it clean, secure, and reproducible, please follow these guidelines.
+
+---
+
+## 📦 Repository Hygiene
+
+- **Do NOT commit secrets**  
+  Never commit tokens, passwords, vault keys, or private inventories.  
+  Use `~/.railiance_gitea.conf` for local config.
+
+- **Line endings**  
+  - Always **LF (`\n`)**, never CRLF.  
+  - Enforced via `.editorconfig` and `.gitattributes`.
+
+- **Ignore local junk**  
+  Check `.gitignore` — if a file is listed there, it must not be versioned.
+
+---
+
+## 🛠 Code Style
+
+- **YAML / Ansible / K8s manifests:** 2 spaces indentation.  
+- **Python:** 4 spaces indentation, PEP8 where reasonable.  
+- **Shell scripts:** 2 spaces, `set -euo pipefail`, and `#!/usr/bin/env bash`.
+
+- Keep scripts **idempotent** (safe to re-run without breaking).  
+- Add comments generously — this repo is also documentation.
+
+---
+
+## 🔄 Workflow
+
+1. **Branching**  
+   - Use feature branches: `feature/<topic>`  
+   - Bugfixes: `fix/<topic>`  
+   - Infrastructure experiments: `exp/<topic>`
+
+2. **Commits**  
+   - Keep them small, focused, and with clear messages.  
+   - Prefix optional: `feat:`, `fix:`, `chore:`, `docs:`, `test:`.
+
+3. **Pull Requests**  
+   - Every change should come via PR, even small fixes.  
+   - PR description: what, why, and how tested.  
+   - At least one review before merge (self-review counts if solo).
+
+---
+
+## ✅ Testing
+
+- Each automation step should be verifiable with a test (`tests/`).  
+- Run tests locally before pushing.  
+- If you add a new playbook or Helm chart, add or update a corresponding test.
+
+---
+
+## 🤖 AI & Automation
+
+Railiance assumes **AI-first workflows**.  
+- Scripts should provide clear outputs that can be parsed by agents.  
+- Logs must be machine- and human-readable.  
+- Favor **convention over configuration** — less choice, more clarity.
+
+---
+
+## 🌱 Philosophy
+
+- **Convention over configuration**: prefer defaults.  
+- **Don’t repeat yourself**: centralize config.  
+- **Calm ops**: keep infra resilient and predictable.  
+- **Self-reliance**: everything must bootstrap from bare metal + this repo.
+
+---
+
+## 🚫 What Not to Do
+
+- Don’t hard-code IPs, tokens, or passwords.  
+- Don’t commit binaries (except intentionally versioned Helm charts).  
+- Don’t bypass review by committing directly to `main`.
+
+---
+
+✌️ Happy hacking!  
+Let’s keep Railiance simple, reproducible, and fun.