diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..975cc1a
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,25 @@
+# Contributing
+
+Thanks for looking at **playkit**.
+
+## How this repo is published
+
+- **Public mirror:** [github.com/Gitilia/playkit](https://github.com/Gitilia/playkit)
+- **Development + CI:** private forge (Gitea). npm publishes to a private registry used by Levkin apps.
+
+## Issues
+
+GitHub **issues** are welcome for bugs, API ideas, and docs gaps.
+
+## Pull requests
+
+Small docs/test fixes via GitHub PR are fine. For larger API changes, open an issue first so we can align — the mirror may lag the forge, and merge gates run on the forge.
+
+## Local setup
+
+```bash
+npm install
+npm test
+```
+
+See the README for consumer install (`@levkin/playkit`) and fixture examples.
diff --git a/README.md b/README.md
index f738b0d..37f7000 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,12 @@
 # @levkin/playkit
 
-Shared **Playwright + API** test kit for Levkin / homelab apps.
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5-blue)](https://www.typescriptlang.org/)
+[![Playwright](https://img.shields.io/badge/Playwright-ready-45ba4b)](https://playwright.dev/)
 
-Use it as a library from any consumer repo (punimtag, MirrorMatch, …). App-specific Page Objects and specs stay in the consumer; reusable helpers, logging, API client, performance timings, and Grafana/Prometheus metrics live here.
+**Shared Playwright + API test helpers** — resilient UI actions, API client, timings, and metrics used across Levkin apps.
+
+> Public mirror: [github.com/Gitilia/playkit](https://github.com/Gitilia/playkit) · issues welcome here; CI/publish run on the private forge.
 
 ## Install (consumer)