Update docs

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,87 @@
+name: Bug Report
+description: Report a bug with Reference Graph
+labels: ["bug"]
+body:
+  - type: textarea
+    id: screenshot
+    attributes:
+      label: Screenshot
+      description: Please attach a screenshot or GIF showing the issue. This is critical for visual bugs.
+      placeholder: Drag and drop an image here
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened? What did you expect to happen?
+      placeholder: |
+        When I run "Show Reference Graph" on a function...
+
+        Expected: ...
+        Actual: ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: How can we reproduce this issue?
+      placeholder: |
+        1. Open a TypeScript file
+        2. Place cursor on function `foo`
+        3. Right-click → "Show Reference Graph"
+        4. See error...
+    validations:
+      required: true
+
+  - type: input
+    id: language
+    attributes:
+      label: Language / File Type
+      description: What language or file type were you using?
+      placeholder: "TypeScript, Vue, Python, etc."
+    validations:
+      required: true
+
+  - type: input
+    id: extension-version
+    attributes:
+      label: Extension Version
+      description: Reference Graph version (Extensions sidebar → Reference Graph → gear icon)
+      placeholder: "0.0.2"
+    validations:
+      required: true
+
+  - type: textarea
+    id: vscode-version
+    attributes:
+      label: VS Code Version
+      description: "Copy from: Help → About"
+      placeholder: |
+        Version: 1.85.0
+        Commit: ...
+        Date: ...
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - macOS
+        - Windows
+        - Linux
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other relevant information (console errors, related extensions, etc.)
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What feature or improvement would you like to see?
+      placeholder: |
+        I'd like to be able to...
+
+        This would help because...
+    validations:
+      required: true
+
+  - type: textarea
+    id: mockup
+    attributes:
+      label: Mockup / Example
+      description: If applicable, attach a mockup, screenshot, or example of how this might work
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,62 @@
+## Screenshot
+
+<!-- REQUIRED: Attach a screenshot or GIF showing the change -->
+
+## Summary
+
+<!-- Brief description of what this PR does -->
+
+## Manual QA Checklist
+
+<!-- Check all items you've verified. Leave unchecked items with a note if not applicable. -->
+
+### Graph Rendering
+- [ ] Nodes don't overlap each other
+- [ ] Edges route cleanly (no edge-node overlaps)
+- [ ] Root node has distinct styling
+- [ ] Layout fits well for your test case
+
+### Navigation
+- [ ] Click node → correct file opens at correct line
+- [ ] Editor gains focus after click (not stuck in webview)
+
+### Node Expansion
+- [ ] "expand" label appears on expandable nodes
+- [ ] Clicking expand adds new nodes to graph
+- [ ] Graph re-layouts smoothly after expansion
+
+### Search (Cmd/Ctrl+F)
+- [ ] Search bar opens
+- [ ] Matching nodes highlight
+- [ ] Enter cycles to next match
+- [ ] Shift+Enter cycles to previous match
+- [ ] View auto-centers on focused match
+- [ ] Escape closes search
+
+### File Filter
+- [ ] Include pattern filters correctly (e.g., `src/**/*.ts`)
+- [ ] Exclude pattern filters correctly
+- [ ] "Hide filtered nodes" removes nodes (vs dimming)
+- [ ] Node count updates correctly
+
+### Hide Imports
+- [ ] Checkbox toggles import node visibility
+
+### Export PNG
+- [ ] Button triggers save dialog
+- [ ] Saved image contains visible nodes
+
+### Code Preview
+- [ ] Syntax highlighting renders correctly
+- [ ] Referenced symbol is highlighted in snippet
+
+### States
+- [ ] Loading spinner shows while building graph
+- [ ] Error message displays for invalid symbols
+
+### Console
+- [ ] No errors in webview DevTools (F12 in Extension Host)
+
+## Notes
+
+<!-- Any context, trade-offs, or areas you're unsure about -->

AGENTS.md

@@ -2,71 +2,29 @@
 
 VS Code extension that visualizes code references as an interactive graph.
 
-## Commands
-
-```bash
-npm install && cd webview-ui && npm install && cd ..  # Install deps
-npm run build          # Build all (extension + webview)
-npm run watch          # Watch mode (extension only)
-npm run lint           # ESLint
-npm run test           # Run tests
-```
-
-Debug: Press F5 in VS Code to launch Extension Development Host.
-
-## Project Layout
-
-| Area | Entry Point | Look Here For |
-|------|-------------|---------------|
-| Extension | `src/extension.ts` | Command registration, activation |
-| Graph logic | `src/graph/GraphBuilder.ts` | Reference traversal, node/edge building |
-| File refs | `src/fileReferences/` | File reference provider architecture |
-| Webview host | `src/webview/WebviewProvider.ts` | Panel creation, message handling |
-| React app | `webview-ui/src/App.tsx` | UI state, message reception |
-| Graph UI | `webview-ui/src/components/ReferenceGraph.tsx` | React Flow setup |
-| Layout | `webview-ui/src/hooks/useElkLayout.ts` | ELK.js configuration |
-| Types | `src/graph/types.ts` | All shared type definitions |
-
-## Architecture Notes
-
-- **Two runtimes**: Extension (Node.js) and Webview (Chromium) communicate via `postMessage`
-- **Dual traversal strategy**: Call Hierarchy API for functions, References API for other symbols
-- **File reference providers**: Language-agnostic architecture with priority-based selection (see below)
-- **Build outputs**: `out/extension.js` (extension) + `out/webview-assets/` (webview bundle)
-
-For details, read the source files directly. Types and data flow are self-documenting.
-
-### File Reference Provider Architecture
-
-The file reference feature uses a provider pattern for language-specific optimizations:
-
-| Component | Path | Purpose |
-|-----------|------|---------|
-| Interface | `src/fileReferences/types.ts` | `FileReferenceProvider` contract |
-| Registry | `src/fileReferences/FileReferenceRegistry.ts` | Singleton, priority-based selection |
-| Resolver | `src/fileReferences/FileReferenceResolver.ts` | Entry point for lookups |
-| Generic | `src/fileReferences/providers/GenericFileReferenceProvider.ts` | Fallback (priority: -10) |
-| TypeScript | `src/fileReferences/providers/TypeScriptFileReferenceProvider.ts` | TS/JS optimized (priority: 10) |
-
-**Adding a new provider:**
-1. Implement `FileReferenceProvider` interface
-2. Register in `src/fileReferences/providers/index.ts`
-3. Higher priority wins when multiple providers match
+For commands, project structure, and architecture details, see **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)**.
 
 ## Documentation Rules (CRITICAL)
 
 **Single Source of Truth:**
-- `README.md` — User-facing documentation (features, usage, shortcuts)
-- `AGENTS.md` — Agent workflow instructions (this file)
-- `package.json` — Extension manifest, commands, configuration schema
+
+| Document | Purpose |
+|----------|---------|
+| `README.md` | User-facing documentation (features, usage) |
+| `CONTRIBUTING.md` | Contributor guidelines (PRs, tests, fixtures) |
+| `docs/DEVELOPMENT.md` | Technical reference (commands, structure, architecture) |
+| `AGENTS.md` | Agent workflow instructions (this file) |
+| `package.json` | Extension manifest, commands, configuration schema |
 
 **When to update what:**
+
 | Change | Update |
 |--------|--------|
 | New user-facing feature | `README.md` |
 | New command or config option | `package.json` contributes section |
-| New npm script | `package.json` scripts section |
-| Changed project structure | `AGENTS.md` Project Layout table |
+| New npm script | `package.json` scripts, `docs/DEVELOPMENT.md` Commands |
+| Changed project structure | `docs/DEVELOPMENT.md` Project Structure table |
+| Test/fixture patterns | `CONTRIBUTING.md` |
 | Internal refactoring | Nothing (code is the documentation) |
 
 **Never duplicate information across files.** If something is defined in code (types, config), point to the file instead of copying content.

CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing to Reference Graph
+
+PRs are welcome! This document explains how to contribute effectively.
+
+For commands and project structure, see **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)**.
+
+## Writing Tests
+
+### General Guidelines
+
+- **Add to existing test suites** when extending existing functionality
+- **Create new fixtures** when testing new languages or patterns
+- **Follow existing patterns** — look at similar tests for reference
+
+### Fixture Structure
+
+Fixtures live in `src/test/fixtures/`. Each fixture directory should be self-contained:
+
+```
+src/test/fixtures/
+├── file-references/        # TypeScript file import tests
+│   ├── core.ts
+│   ├── consumer.ts
+│   ├── anotherConsumer.ts
+│   └── tsconfig.json
+├── vue-file-references/    # Vue file import tests
+│   ├── core.vue
+│   ├── consumer.vue
+│   ├── anotherConsumer.vue
+│   ├── tsconfig.json
+│   └── package.json
+└── symbol-references/      # Symbol reference tests
+    ├── utils.ts
+    ├── service.ts
+    ├── config.ts
+    └── tsconfig.json
+```
+
+**When adding a new language provider**, create a corresponding fixture directory with:
+- Sample source files demonstrating import/export patterns
+- Necessary config files (`tsconfig.json`, `package.json`, etc.)
+- At least 3 files to test the reference chain (root → consumer → leaf)
+
+### Test Pattern
+
+```typescript
+suite('MyLanguage FileReferenceResolver Test Suite', function () {
+    this.timeout(30000);  // Language servers need time
+
+    suiteSetup(async () => {
+        registerBuiltinProviders();
+        await waitForLanguageServer();  // Wait for relevant extension
+        // Open fixture files to trigger language server
+    });
+
+    test('finds files that import core file', async () => {
+        const resolver = new FileReferenceResolver();
+        const coreUri = vscode.Uri.file(path.join(fixturesPath, 'core.xyz'));
+
+        const references = await resolver.findFileReferences(coreUri);
+        const referringFiles = references.map(r => path.basename(r.uri.fsPath)).sort();
+
+        assert.deepStrictEqual(referringFiles, ['consumer.xyz', 'other.xyz']);
+    });
+});
+```
+
+## Adding a New Language Provider
+
+See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md#adding-a-new-provider) for the implementation guide.
+
+**After implementing, add tests:**
+
+1. Create fixture directory: `src/test/fixtures/mylang-file-references/`
+2. Add test cases to `src/test/fileReferences.test.ts` or create a new test file
+3. Test with real-world code, not just fixtures
+
+## Code Style
+
+- Run `npm run lint:all` before committing
+- Follow existing patterns in the codebase
+- TypeScript strict mode is enabled
+
+## Questions?
+
+Open an issue if you have questions or want to discuss a feature before implementing.

README.ja.md

@@ -0,0 +1,45 @@
+# Reference Graph
+
+[English](README.md) | 日本語 | [简体中文](README.zh-CN.md)
+
+コード参照をインタラクティブなグラフで可視化します。
+
+![Reference Graph Demo](screenshot.gif)
+
+## 機能
+
+- **インタラクティブなグラフ表示**: React Flowを使用して、シンボルへの全ての参照を接続されたグラフとして表示
+- **コードプレビュー**: 各ノードに参照箇所の前後3行をシンタックスハイライト付きで表示
+- **シンボルハイライト**: コードスニペット内の参照されたシンボルをハイライト表示
+- **スマートレイアウト**: ELKjsによるノードサイズを考慮した自動グラフレイアウト
+- **ファイルフィルタリング**: globパターンでノードをフィルタリング（例: `src/**/*.ts`, `**/test/**`）
+- **PNG出力**: 現在のグラフ表示をPNG画像として保存
+- **クリックでナビゲート**: ノードをクリックしてエディタの該当位置にジャンプ
+
+## 使い方
+
+1. 関数、変数、その他のシンボルにカーソルを置く
+2. 右クリックして「Show Reference Graph」を選択、またはコマンドパレットから実行
+3. サイドパネルに全ての参照を示すグラフが表示されます
+
+### ノードのフィルタリング
+
+左上のフィルターパネルで特定のファイルに絞り込めます:
+- **Files to include**: 指定パターンに一致するファイルのみ表示（例: `src/**/*.ts`）
+- **Files to exclude**: 指定パターンに一致するファイルを非表示（例: `**/node_modules/**`）
+- **Hide filtered nodes**: フィルタリングされたノードを薄暗くする代わりに完全に非表示にする
+
+パターンはglob構文を使用します — `**` は任意のディレクトリ階層、`*` は任意のファイル名にマッチします。
+
+### PNGとして出力
+
+右上の **Export PNG** ボタンをクリックすると、現在のグラフ表示を画像として保存できます。
+
+## 要件
+
+- VS Code 1.80.0 以上
+- "Find All References" をサポートする言語サーバー
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).