diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..a711014
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,40 @@
+# Contributing to numkey
+
+Thanks for your interest! Issues and pull requests are welcome — bug reports,
+locale quirks, docs fixes, and new ideas alike. 이슈·PR 환영합니다 (한국어로
+쓰셔도 됩니다).
+
+## Dev setup
+
+```sh
+git clone https://github.com/devslab-kr/numkey.git
+cd numkey
+npm install
+npm test # vitest (core + jsdom DOM/caret + Vue mount tests)
+npm run typecheck
+npm run build # ESM/CJS + dist/numkey.global.js (CDN build)
+```
+
+The demo site is `site/index.html` — after `npm run build`, copy
+`dist/numkey.global.js*` into `site/` and open it (the copies are
+gitignored; the Pages workflow assembles fresh ones on deploy).
+
+## Guidelines
+
+- **Every behavior change needs a test.** Caret behavior is the heart of the
+ library — for input-flow bugs, write the regression test the way a user
+ types (char by char), not by assigning the whole value at once; that
+ difference has caught real bugs here.
+- The canonical value model is string-first on purpose (money-safe, never
+ IEEE 754) — PRs that route values through `Number` will be asked to rework.
+- Don't touch the input mid-IME-composition; anything running on `input`
+ events must stay behind the composition guard.
+- `react` is intentionally NOT a devDependency — React adapters share the
+ tested `dom.ts` building blocks; Vue components are mount-tested.
+- Keep docs bilingual where structure allows (README.md / README.ko.md).
+
+## Releases
+
+Maintainer-driven via a dispatch workflow — you don't need to touch
+versions, tags, or the CHANGELOG header format in a feature PR; just add an
+entry describing your change under the unreleased heading if one exists.
diff --git a/README.ko.md b/README.ko.md
index 4bae911..c6627d3 100644
--- a/README.ko.md
+++ b/README.ko.md
@@ -4,6 +4,10 @@
바로 실행해보기: [⚡ StackBlitz — Vanilla](https://stackblitz.com/github/devslab-kr/numkey/tree/main/examples/vanilla) · [Vue](https://stackblitz.com/github/devslab-kr/numkey/tree/main/examples/vue) · [React](https://stackblitz.com/github/devslab-kr/numkey/tree/main/examples/react) | [📦 CodeSandbox](https://codesandbox.io/s/github/devslab-kr/numkey/tree/main/examples/vanilla)
+
+ 
+
+
[](https://www.npmjs.com/package/@devslab/numkey)
[](https://github.com/devslab-kr/numkey/actions/workflows/ci.yml)
[](./LICENSE)
@@ -264,6 +268,12 @@ const [amount, setAmount] = useState('')
건너뛰고, 재포맷이 나머지를 처리).
- 로드맵: 인도식 lakh 그룹핑 (`12,34,567` — 비균일 그룹 크기).
+## 기여하기
+
+이슈·PR 환영합니다 — 개발 환경 셋업과 규칙(문자열 우선 값 모델, IME 안전,
+한 글자씩 타이핑하는 regression 테스트)은
+[CONTRIBUTING.md](./CONTRIBUTING.md)를 보세요.
+
## License
MIT © [devslab](https://github.com/devslab-kr)
diff --git a/README.md b/README.md
index da4461a..f59da6c 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,10 @@
Try it online: [⚡ StackBlitz — Vanilla](https://stackblitz.com/github/devslab-kr/numkey/tree/main/examples/vanilla) · [Vue](https://stackblitz.com/github/devslab-kr/numkey/tree/main/examples/vue) · [React](https://stackblitz.com/github/devslab-kr/numkey/tree/main/examples/react) | [📦 CodeSandbox](https://codesandbox.io/s/github/devslab-kr/numkey/tree/main/examples/vanilla)
+
+
+
+
[](https://www.npmjs.com/package/@devslab/numkey)
[](https://github.com/devslab-kr/numkey/actions/workflows/ci.yml)
[](./LICENSE)
@@ -267,6 +271,12 @@ const [amount, setAmount] = useState('')
one keystroke (the separator is skipped, and the reformat handles the rest).
- Roadmap: Indian lakh grouping (`12,34,567` — non-uniform group sizes).
+## Contributing
+
+Issues and PRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md) for the dev
+setup and the ground rules (string-first values, IME safety, char-by-char
+regression tests).
+
## License
MIT © [devslab](https://github.com/devslab-kr)
diff --git a/docs/preview.png b/docs/preview.png
new file mode 100644
index 0000000..090530f
Binary files /dev/null and b/docs/preview.png differ