docs: add contributor onboarding templates and guides

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,65 @@
+name: Bug report
+description: Report a reproducible defect in FlowMap.
+title: "[Bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug. Please provide a minimal reproduction so we can fix it quickly.
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What is broken?
+      placeholder: FlowMap does not show changed nodes when saving Swift files.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: Provide exact steps from a clean workspace.
+      placeholder: |
+        1. Open workspace ...
+        2. Save file ...
+        3. Run FlowMap: Analyze Workspace ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      placeholder: Changed node should be highlighted as yellow.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      placeholder: No diff highlight appears.
+    validations:
+      required: true
+
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      description: OS, Xcode/Swift version, VS Code version, extension version.
+      placeholder: macOS 14.7, Swift 6.0, VS Code 1.98, FlowMap commit abc123
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / screenshots
+      description: Include console logs, screenshots, or replay output if relevant.
+      placeholder: Paste logs here.
+    validations:
+      required: false
+

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Usage question
+    url: mailto:adgk2349b@gmail.com
+    about: Ask usage or setup questions by email.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,48 @@
+name: Feature request
+description: Suggest an improvement for FlowMap.
+title: "[Feature] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please describe the user problem first, then propose a solution.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What pain point are you trying to solve?
+      placeholder: It is hard to detect risky graph diffs at a glance.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What should change?
+      placeholder: Add risk score badge for diff mode.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      placeholder: Keep current legend only, add external script, etc.
+    validations:
+      required: false
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: Define testable outcomes.
+      placeholder: |
+        - [ ] Badge appears in diff mode
+        - [ ] Risk score updates on save
+        - [ ] Unit tests added
+    validations:
+      required: true
+

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+## Summary
+
+<!-- What problem does this PR solve? -->
+
+## What Changed
+
+<!-- Briefly list key code/doc changes -->
+
+## Validation
+
+<!-- Paste commands and key outputs -->
+
+```bash
+cargo test
+```
+
+## Screenshots / Demo (if UI changed)
+
+<!-- Before/After screenshots or GIF -->
+
+## Checklist
+
+- [ ] Linked related issue (if available)
+- [ ] Added/updated tests for behavior changes
+- [ ] Ran required local checks (`fmt`, `clippy`, `test`, extension compile/lint)
+- [ ] Updated docs/README if user-visible behavior changed
+- [ ] Included replay/scenario report when diff detection behavior changed
+

CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing to FlowMap
+
+Thanks for contributing to FlowMap.
+
+This document is optimized for first-time contributors. If you are looking for a starting point, check [docs/good-first-issues.md](docs/good-first-issues.md).
+
+## Quick Start (5-10 minutes)
+
+1. Fork and clone this repository.
+2. Create a branch:
+   - `feat/<short-topic>` for features
+   - `fix/<short-topic>` for fixes
+   - `docs/<short-topic>` for documentation
+3. Run local checks before opening a PR.
+
+## Local Setup
+
+Prerequisites:
+
+- macOS
+- Rust toolchain
+- Swift toolchain / Xcode command line tools
+- Node.js 20+
+
+Build commands:
+
+```bash
+cargo build
+cd parsers/swift-ast && swift build -c release && cd ../..
+cd editor/vscode && npm ci && npm run compile && cd ../..
+```
+
+## Required Checks Before PR
+
+Run these in repo root:
+
+```bash
+cargo fmt --check
+cargo clippy -- -D warnings
+cargo test
+cd editor/vscode && npm run lint && npm run compile && cd ../..
+```
+
+If your change affects analysis/diff behavior, also attach validation output:
+
+```bash
+node scripts/run_sample_scenarios.mjs --report reports/sample-scenarios-report.json
+node scripts/run_commit_replay.mjs --repo /path/to/swift-repo --count 20 --report reports/replay-local.json
+```
+
+## Pull Request Guidelines
+
+- Keep PR scope small and reviewable.
+- Include a short problem statement and what changed.
+- Include before/after behavior.
+- For graph UI changes, include screenshots or GIF.
+- For parser/engine logic changes, include at least one regression test.
+
+Maintainer target: first review response within 48 hours for new contributors.
+
+## First Contribution Checklist
+
+- Pick one item from [docs/good-first-issues.md](docs/good-first-issues.md)
+- Reproduce and confirm current behavior
+- Add or update tests
+- Run required checks
+- Open PR using the provided PR template
+- Request review
+
+## Reporting Issues
+
+Use GitHub Issue templates:
+
+- Bug report: reproducible defect
+- Feature request: problem + proposal + acceptance criteria
+
+## Code Style Notes
+
+- Rust: keep clippy clean; avoid panic-prone changes in engine paths.
+- TypeScript/JS: keep webview code modular (`graph.*.js` split).
+- Swift parser: prioritize stable JSON schema output for engine compatibility.
+
+## Validation Evidence in README
+
+Bundled validation reports live under `reports/`. If you update benchmark/replay reports, include:
+
+- what dataset/repo was used
+- command used
+- summary metrics (TP/TN/FP/FN, detection rate)
+

README.ja.md

@@ -2,6 +2,8 @@
 
 > Swift コードの構造と呼び出し関係をグラフ分析するツールです。AI が生成したコード変更の検証に特に役立ちます。
 
+[![CI](https://github.com/adgk2349/FlowMap/actions/workflows/ci.yml/badge.svg)](https://github.com/adgk2349/FlowMap/actions/workflows/ci.yml)
+
 [English](README.md) · [한국어](README.ko.md)
 
 ## FlowMap とは
@@ -136,6 +138,14 @@ node scripts/run_commit_replay.mjs \
 - `reports/replay-validation-bundle.md`
 - `reports/replay-validation-bundle.json`
 
+最新の統合メトリクス（`reports/replay-validation-bundle.md`）:
+
+- コミットペア総数: 209
+- TP / TN / FP / FN: 106 / 97 / 0 / 6
+- Non-Swift FP Rate: 0%
+- Swift Detection Rate: 94.64%
+- Overall Match Rate: 97.13%
+
 ## ライセンス
 
 FlowMap は source-available モデルで提供されています。
@@ -161,6 +171,10 @@ FlowMap は source-available モデルで提供されています。
 
 Issue と Pull Request を歓迎します。
 
+- コントリビューションガイド: [CONTRIBUTING.md](CONTRIBUTING.md)
+- 初回向けタスク一覧: [docs/good-first-issues.md](docs/good-first-issues.md)
+- Issue / PR は `.github` のテンプレートを利用してください
+
 貢献しやすい領域:
 
 - Swift 解析の edge case

README.ko.md

@@ -2,6 +2,8 @@
 
 > Swift 코드의 구조와 호출 관계를 그래프로 분석하는 도구입니다. AI가 생성한 코드 변경을 검증할 때 특히 유용합니다.
 
+[![CI](https://github.com/adgk2349/FlowMap/actions/workflows/ci.yml/badge.svg)](https://github.com/adgk2349/FlowMap/actions/workflows/ci.yml)
+
 [English](README.md) · [日本語](README.ja.md)
 
 ## FlowMap이란?
@@ -136,6 +138,14 @@ node scripts/run_commit_replay.mjs \
 - `reports/replay-validation-bundle.md`
 - `reports/replay-validation-bundle.json`
 
+최신 통합 지표(`reports/replay-validation-bundle.md`):
+
+- 전체 커밋 페어: 209
+- TP / TN / FP / FN: 106 / 97 / 0 / 6
+- Non-Swift FP Rate: 0%
+- Swift Detection Rate: 94.64%
+- Overall Match Rate: 97.13%
+
 ## 라이선스
 
 FlowMap은 source-available 방식으로 제공됩니다.
@@ -161,6 +171,10 @@ FlowMap은 source-available 방식으로 제공됩니다.
 
 이슈와 PR은 환영합니다.
 
+- 기여 가이드: [CONTRIBUTING.md](CONTRIBUTING.md)
+- 시작용 작업 목록: [docs/good-first-issues.md](docs/good-first-issues.md)
+- 이슈/PR 작성 시 `.github` 템플릿을 사용해주세요
+
 기여하기 좋은 영역:
 
 - Swift 파싱 edge case

README.md

@@ -2,6 +2,8 @@
 
 > Swift code graph and impact analysis tool — understand and verify code structure, especially when reviewing AI-generated changes.
 
+[![CI](https://github.com/adgk2349/FlowMap/actions/workflows/ci.yml/badge.svg)](https://github.com/adgk2349/FlowMap/actions/workflows/ci.yml)
+
 [한국어](README.ko.md) · [日本語](README.ja.md)
 
 ## What is FlowMap?
@@ -136,6 +138,14 @@ Current bundled validation output:
 - `reports/replay-validation-bundle.md`
 - `reports/replay-validation-bundle.json`
 
+Latest bundled metrics (`reports/replay-validation-bundle.md`):
+
+- Total commit pairs: 209
+- TP / TN / FP / FN: 106 / 97 / 0 / 6
+- Non-Swift FP Rate: 0%
+- Swift Detection Rate: 94.64%
+- Overall Match Rate: 97.13%
+
 ## License
 
 FlowMap is source-available.
@@ -161,6 +171,10 @@ For commercial licensing inquiries, contact: adgk2349b@gmail.com
 
 Issues and pull requests are welcome.
 
+- Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Starter tasks: [docs/good-first-issues.md](docs/good-first-issues.md)
+- Use the Issue/PR templates in `.github/`
+
 Good areas to contribute:
 
 - Swift parsing edge cases