docs: demo preview screenshot + CONTRIBUTING

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.

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)
 
+<p align="center">
+  <a href="https://devslab-kr.github.io/numkey/"><img src="https://raw.githubusercontent.com/devslab-kr/numkey/main/docs/preview.png" alt="numkey 데모 — 실시간 천 단위 콤마, 한글 금액 병기 (150만 원), 붙여넣기 정제" width="720"></a>
+</p>
+
 [![npm](https://img.shields.io/npm/v/%40devslab%2Fnumkey)](https://www.npmjs.com/package/@devslab/numkey)
 [![CI](https://github.com/devslab-kr/numkey/actions/workflows/ci.yml/badge.svg)](https://github.com/devslab-kr/numkey/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/%40devslab%2Fnumkey)](./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)

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)
 
+<p align="center">
+  <a href="https://devslab-kr.github.io/numkey/"><img src="https://raw.githubusercontent.com/devslab-kr/numkey/main/docs/preview.png" alt="numkey demo — live thousands grouping, Korean amount reading (150만 원), paste sanitizing" width="720"></a>
+</p>
+
 [![npm](https://img.shields.io/npm/v/%40devslab%2Fnumkey)](https://www.npmjs.com/package/@devslab/numkey)
 [![CI](https://github.com/devslab-kr/numkey/actions/workflows/ci.yml/badge.svg)](https://github.com/devslab-kr/numkey/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/%40devslab%2Fnumkey)](./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)