diff --git a/README.ko.md b/README.ko.md
new file mode 100644
index 0000000..56f9b42
--- /dev/null
+++ b/README.ko.md
@@ -0,0 +1,517 @@
+# 📖 github-mobile-reader
+
+> `github-mobile-reader`는 git diff를 깔끔하게 세로 스크롤로 읽을 수 있는 Markdown 문서로 변환합니다 — 더 이상 좌우 핀치줌이나 가로 스와이프는 필요 없습니다.
+
+[![npm version](https://img.shields.io/npm/v/github-mobile-reader.svg)](https://www.npmjs.com/package/github-mobile-reader)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js ≥ 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+> 영어 문서는 [README.md](./README.md)에서 확인하세요.
+
+---
+
+## 문제 상황
+
+GitHub의 모바일 웹 뷰는 코드를 고정 너비의 모노스페이스 블록으로 렌더링합니다. 긴 줄은 가로 스크롤을 요구하고, 깊게 중첩된 로직은 한눈에 파악이 불가능하며, 출퇴근 지하철에서 PR 리뷰를 하는 건 사실상 불가능에 가깝습니다.
+
+## 해결책
+
+`github-mobile-reader`는 git diff를 파싱해서 **Logical Flow** — 단순히 어떤 문자가 바뀌었는지가 아니라 *코드가 무엇을 하는지*를 보여주는 간결한 트리 — 를 생성합니다. 결과물은 어떤 화면 너비에서도 위에서 아래로 읽히는 Markdown 문서입니다.
+
+**Before** (기존 diff, 모바일 웹):
+
+```
+← 스와이프 → 스와이프 → 스와이프 →
++ const result = data.map(item => item.value).filter(v => v > 10).reduce((a,b) => a+b, 0)
+```
+
+**After** (Reader Markdown):
+
+```
+data
+ └─ map(item → value)
+     └─ filter(callback)
+         └─ reduce(callback)
+```
+
+---
+
+## 주요 기능
+
+- **의존성 제로 코어** — 파서는 Node.js ≥ 18이 있는 어디서나 동작합니다
+- **이중 출력 포맷** — CJS (`require`)와 ESM (`import`) 모두 지원, TypeScript 타입 포함
+- **GitHub Action** — 레포에 YAML 파일 하나만 추가하면 PR마다 Reader 문서가 자동 생성됩니다
+- **양방향 diff 추적** — 추가된 코드와 삭제된 코드를 각각 별도 섹션으로 표시
+- **보수적 설계** — 패턴이 애매할 때는 잘못된 정보를 보여주는 대신 덜 보여줍니다
+
+---
+
+## 목차
+
+1. [빠른 시작](#빠른-시작)
+2. [언어 지원](#언어-지원)
+3. [GitHub Action (권장)](#github-action-권장)
+4. [npm 라이브러리 사용법](#npm-라이브러리-사용법)
+5. [출력 형식](#출력-형식)
+6. [API 레퍼런스](#api-레퍼런스)
+7. [파서 동작 원리](#파서-동작-원리)
+8. [기여하기](#기여하기)
+9. [라이선스](#라이선스)
+
+---
+
+## 빠른 시작
+
+```bash
+npm install github-mobile-reader
+```
+
+```ts
+import { generateReaderMarkdown } from "github-mobile-reader";
+import { execSync } from "child_process";
+
+const diff = execSync("git diff HEAD~1", { encoding: "utf8" });
+const markdown = generateReaderMarkdown(diff, { file: "src/utils.ts" });
+
+console.log(markdown);
+```
+
+---
+
+## 언어 지원
+
+파서는 정규식 기반 패턴 매칭으로 동작하므로 기술적으로는 어떤 언어의 diff도 입력받을 수 있습니다. 다만 감지 패턴이 JavaScript/TypeScript 문법에 맞춰 설계되어 있어 **Logical Flow 출력 품질이 언어마다 다릅니다**.
+
+### 현재 지원 현황 (v0.1)
+
+| 언어                    | 확장자                    |      품질      | 비고                                                                        |
+| ----------------------- | ------------------------- | :------------: | --------------------------------------------------------------------------- |
+| **JavaScript**          | `.js` `.mjs` `.cjs`       |    ✅ 완전     | 파서의 기준 언어                                                            |
+| **TypeScript**          | `.ts`                     |    ✅ 완전     | JS 상위 집합 — 모든 패턴 적용                                               |
+| **React JSX**           | `.jsx`                    |    ✅ 완전     | JS와 동일한 문법                                                            |
+| **React TSX**           | `.tsx`                    |    ✅ 완전     | TS와 동일한 문법                                                            |
+| **Next.js**             | `.js` `.ts` `.jsx` `.tsx` |    ✅ 완전     | JS/TS 위에서 동작하는 프레임워크                                            |
+| **Java**                | `.java`                   | ⚠️ 부분 (~55%) | `if/for/while`과 체이닝은 동작; 함수 선언 감지 실패 (`const/let/var` 없음)  |
+| **C#**                  | `.cs`                     | ⚠️ 부분 (~35%) | LINQ 체이닝(`.Where().Select()`)은 동작; `using`/`namespace`/`class` 미감지 |
+| **C**                   | `.c` `.h`                 | ❌ 최소 (~15%) | 매칭 키워드 없음; 포인터 문법(`->`, `*`) 미지원                             |
+| **Python, Go, Rust 등** | —                         |    🔜 예정     | 아래 로드맵 참고                                                            |
+
+> **참고:** Java, C#, C 파일은 기본적으로 GitHub Action에서 처리되지 않습니다.
+> Action은 `.js .jsx .ts .tsx .mjs .cjs` 파일만 스캔합니다 ([`src/action.ts` 66번째 줄](src/action.ts)).
+> 다른 언어를 처리하려면 커스텀 어댑터가 필요합니다 ([기여하기](#기여하기) 참고).
+
+### JS/TS/React/Next.js가 완전 지원되는 이유
+
+네 가지 모두 동일한 기반 문법을 공유합니다. 파서가 인식하는 것:
+
+- **메서드 체이닝** — `)`나 `}`로 끝나는 줄 다음에 `.`으로 시작하는 줄
+  ```ts
+  data
+    .filter((item) => item.active) // P1 체이닝으로 감지
+    .map((item) => item.value); // P1 체이닝으로 감지
+  ```
+- **함수 선언** — `const`, `let`, `var`, `function`, `async`
+- **조건문** — `if / else / switch`
+- **반복문** — `for / while`
+- **노이즈 필터링** — `import`, `export`, `type`, `interface`, `console.log`는 자동으로 제거
+
+### C / C# / Java가 제한적인 이유
+
+이 언어들은 위 패턴에 대해 다른 표기 방식을 사용합니다:
+
+| 개념          | JS/TS (✅ 감지됨)      | Java / C# / C (❌ 미감지)        |
+| ------------- | ---------------------- | -------------------------------- |
+| 변수 선언     | `const x = …`          | `int x = …` / `String x = …`     |
+| 화살표 콜백   | `x => x.value`         | 언어마다 람다 문법 다름          |
+| 노이즈 import | `import` / `export`    | `using` / `#include` / `package` |
+| 비동기 함수   | `async function foo()` | `async Task<T> Foo()`            |
+
+### 로드맵 — Language Adapter 시스템 (v0.2)
+
+추가 언어 지원을 위해 **Language Adapter** 아키텍처가 계획되어 있습니다:
+
+```
+src/languages/
+├── base.adapter.ts     ← 공통 인터페이스
+├── js-ts.adapter.ts    ← 현재 로직 (parser.ts에서 분리)
+├── java.adapter.ts     ← public/private/void 선언, Stream 체이닝
+└── csharp.adapter.ts   ← using/namespace, LINQ 체이닝
+```
+
+각 어댑터가 제공하는 것:
+
+- 지원 파일 확장자 목록
+- 함수 선언 감지 패턴
+- 무시할 키워드 목록 (노이즈)
+- 체이닝 표기 방식 (점(`.`) vs. 화살표(`->`))
+
+언어 어댑터를 기여하고 싶다면 [기여하기](#기여하기)를 확인하세요.
+
+---
+
+## GitHub Action (권장)
+
+이 라이브러리를 사용하는 가장 쉬운 방법입니다. 매 PR마다 자동으로:
+
+1. 변경된 `.js` / `.ts` 파일의 diff를 파싱
+2. `docs/reader/pr-<번호>.md` 파일을 레포에 저장
+3. PR에 요약 코멘트를 자동으로 달아줍니다
+
+### Step 1 — 워크플로우 파일 추가
+
+레포에 `.github/workflows/mobile-reader.yml`을 만들어 주세요:
+
+```yaml
+name: 📖 Mobile Reader
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: write # .md 파일 커밋
+  pull-requests: write # PR 코멘트 작성
+
+jobs:
+  generate-reader:
+    name: Generate Mobile Reader View
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # git diff에 전체 히스토리 필요
+
+      - name: Generate Reader Markdown
+        uses: 3rdflr/github-mobile-reader@v1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          base_branch: ${{ github.base_ref }}
+          output_dir: docs/reader
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+
+      - name: Commit Reader Markdown
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add docs/reader/
+          if git diff --cached --quiet; then
+            echo "변경사항 없음"
+          else
+            git commit -m "docs(reader): PR #${{ github.event.pull_request.number }} 모바일 리더 업데이트 [skip ci]"
+            git push
+          fi
+```
+
+### Step 2 — PR 열기
+
+이게 전부입니다. 이후 모든 PR에 자동으로:
+
+- `docs/reader/pr-<번호>.md` 파일 생성
+- 생성된 파일 링크가 담긴 PR 코멘트 자동 게시
+
+### Action 입력값
+
+| 입력값         | 필수 | 기본값        | 설명                               |
+| -------------- | ---- | ------------- | ---------------------------------- |
+| `github_token` | ✅   | —             | `${{ secrets.GITHUB_TOKEN }}` 사용 |
+| `base_branch`  | ❌   | `main`        | PR이 머지되는 대상 브랜치          |
+| `output_dir`   | ❌   | `docs/reader` | 생성된 `.md` 파일 저장 경로        |
+
+---
+
+## npm 라이브러리 사용법
+
+CI 스크립트, 커스텀 봇, 로컬 도구 등 모든 Node.js 프로젝트에서 라이브러리로 사용할 수 있습니다.
+
+### 설치
+
+```bash
+# npm
+npm install github-mobile-reader
+
+# pnpm
+pnpm add github-mobile-reader
+
+# yarn
+yarn add github-mobile-reader
+```
+
+### CommonJS
+
+```js
+const { generateReaderMarkdown } = require("github-mobile-reader");
+```
+
+### ESM / TypeScript
+
+```ts
+import {
+  generateReaderMarkdown,
+  parseDiffToLogicalFlow,
+} from "github-mobile-reader";
+```
+
+### 기본 사용 예시
+
+```ts
+import { generateReaderMarkdown } from "github-mobile-reader";
+import { execSync } from "child_process";
+import { writeFileSync } from "fs";
+
+// 마지막 커밋의 diff 가져오기
+const diff = execSync("git diff HEAD~1 HEAD", { encoding: "utf8" });
+
+// 메타데이터와 함께 Reader Markdown 생성
+const markdown = generateReaderMarkdown(diff, {
+  pr: "42",
+  commit: "a1b2c3d",
+  file: "src/api/users.ts",
+  repo: "my-org/my-repo",
+});
+
+// 파일 저장 또는 Slack / Discord / GitHub에 게시
+writeFileSync("reader.md", markdown, "utf8");
+```
+
+### 저수준 API 예시
+
+트리 구조만 필요한 경우 (예: 커스텀 렌더러 제작):
+
+```ts
+import { parseDiffToLogicalFlow, renderFlowTree } from "github-mobile-reader";
+
+const { root, rawCode, removedCode } = parseDiffToLogicalFlow(diff);
+
+// root        → FlowNode[]  (논리 트리)
+// rawCode     → string      (추가된 줄, 줄바꿈으로 연결)
+// removedCode → string      (삭제된 줄, 줄바꿈으로 연결)
+
+const treeLines = renderFlowTree(root);
+console.log(treeLines.join("\n"));
+```
+
+---
+
+## 출력 형식
+
+생성된 Reader Markdown 문서는 네 개의 섹션으로 구성됩니다:
+
+````markdown
+# 📖 GitHub Reader View
+
+> Generated by **github-mobile-reader**
+> Repository: my-org/my-repo
+> Pull Request: #42
+> Commit: `a1b2c3d`
+> File: `src/api/users.ts`
+
+---
+
+## 🧠 Logical Flow
+
+```
+getData()
+ └─ filter(callback)
+     └─ map(item → value)
+         └─ reduce(callback)
+```
+
+## ✅ Added Code
+
+```typescript
+const result = getData()
+  .filter((item) => item.active)
+  .map((item) => item.value)
+  .reduce((a, b) => a + b, 0);
+```
+
+## ❌ Removed Code
+
+```typescript
+const result = getData().map((item) => item.value);
+```
+
+---
+
+🛠 Auto-generated by github-mobile-reader. Do not edit manually.
+````
+
+---
+
+## API 레퍼런스
+
+### `generateReaderMarkdown(diffText, meta?)`
+
+메인 진입점. 원시 git diff 문자열을 파싱해서 완성된 Reader Markdown 문서를 반환합니다.
+
+| 파라미터      | 타입      | 설명                          |
+| ------------- | --------- | ----------------------------- |
+| `diffText`    | `string`  | `git diff`의 원시 출력        |
+| `meta.pr`     | `string?` | PR 번호                       |
+| `meta.commit` | `string?` | 커밋 SHA                      |
+| `meta.file`   | `string?` | 헤더에 표시할 파일명          |
+| `meta.repo`   | `string?` | `owner/repo` 형식의 레포 이름 |
+
+**반환값:** `string` — 완성된 Markdown 문서
+
+---
+
+### `parseDiffToLogicalFlow(diffText)`
+
+렌더링 없이 diff를 구조화된 결과로 파싱합니다.
+
+**반환값:** `ParseResult`
+
+```ts
+interface ParseResult {
+  root: FlowNode[]; // 논리 트리 (추가된 줄)
+  rawCode: string; // 추가된 줄 (\n으로 연결)
+  removedCode: string; // 삭제된 줄 (\n으로 연결)
+}
+```
+
+---
+
+### `renderFlowTree(nodes, indent?)`
+
+`FlowNode[]` 트리를 Markdown 안전한 텍스트 줄 배열로 변환합니다.
+
+```ts
+const lines = renderFlowTree(root);
+// [ 'getData()', ' └─ filter(callback)', ' └─ map(item → value)' ]
+```
+
+---
+
+### `FlowNode`
+
+```ts
+interface FlowNode {
+  type: "root" | "chain" | "condition" | "loop" | "function" | "call";
+  name: string;
+  children: FlowNode[];
+  depth: number;
+  priority: Priority;
+}
+```
+
+---
+
+### `Priority` (열거형)
+
+| 값                | 의미                                            |
+| ----------------- | ----------------------------------------------- |
+| `CHAINING = 1`    | 메서드 체인 (`.map()`, `.filter()`, …) — 최우선 |
+| `CONDITIONAL = 2` | `if` / `else` / `switch` 블록                   |
+| `LOOP = 3`        | `for` / `while` 반복문                          |
+| `FUNCTION = 4`    | 함수 선언                                       |
+| `OTHER = 5`       | 그 외                                           |
+
+---
+
+## 파서 동작 원리
+
+파서는 결정론적 파이프라인으로 동작합니다 — AI 없음, 외부 의존성 없음.
+
+```
+git diff 텍스트
+  │
+  ▼
+1. filterDiffLines()     — + / - 줄 분리, +++ / --- 헤더 제거
+  │
+  ▼
+2. normalizeCode()       — ; 제거, 주석 제거, 공백 정리
+  │
+  ▼
+3. getIndentDepth()      — 중첩 레벨 계산 (2 spaces = 1 레벨)
+  │
+  ▼
+4. parseToFlowTree()     — 우선순위 순서로 패턴 매칭:
+  │                          P1 체이닝  (.map .filter .reduce …)
+  │                          P2 조건문  (if / else / switch)
+  │                          P3 반복문  (for / while)
+  │                          P4 함수 선언
+  │
+  ▼
+5. renderFlowTree()      — 트리 → 들여쓰기된 텍스트 줄로 변환
+  │
+  ▼
+generateReaderMarkdown() — 최종 Markdown 문서 조립
+```
+
+**주요 설계 결정:**
+
+- **보수적** — 분류되지 않는 줄은 잘못된 정보 대신 조용히 건너뜁니다
+- **import / export / type / interface / console.log**는 무시됩니다. 흐름 이해에 기여하지 않기 때문입니다
+- **콜백 인자 축약** — 본문이 단일 속성 접근일 때 `.map(item => item.value)`를 `map(item → value)`로 축약합니다. 그 외에는 `map(callback)`으로 표시합니다
+- **함수 선언은 최우선 체크** — `const foo = async …`가 `extractRoot`에 잘못 분류되지 않도록, 함수 선언 감지를 루트 추출보다 먼저 수행합니다
+- **depth**는 들여쓰기 기반 (2-space 기준)으로 추적되며, 체이닝 감지가 애매할 때 보조 정보로만 사용됩니다
+
+### 지원 언어 (v0.1)
+
+[언어 지원](#언어-지원) 섹션의 전체 표를 확인하세요.
+요약: **JS / TS / React / Next.js 완전 지원**, Java와 C#은 부분 지원, C 등은 Language Adapter 시스템(v0.2)으로 계획 중.
+
+---
+
+## 기여하기
+
+PR은 언제든지 환영합니다! 시작 방법:
+
+```bash
+# 레포 클론
+git clone https://github.com/3rdflr/github-mobile-reader.git
+cd github-mobile-reader
+
+# 의존성 설치
+npm install
+
+# 빌드 (라이브러리 + Action runner)
+npm run build:all
+
+# 개발 중 watch 모드
+npm run dev
+
+# 테스트 실행
+npx ts-node src/test.ts
+```
+
+### 프로젝트 구조
+
+```
+github-mobile-reader/
+├── src/
+│   ├── parser.ts     ← 핵심 diff → logical flow 파서
+│   ├── index.ts      ← npm 공개 API
+│   ├── action.ts     ← GitHub Action 진입점
+│   └── test.ts       ← 스모크 테스트 (33개)
+├── dist/             ← 컴파일 결과물 (자동 생성, 수정 금지)
+├── .github/
+│   └── workflows/
+│       └── mobile-reader.yml   ← 사용자용 예시 워크플로우
+├── action.yml        ← GitHub Action 정의
+├── README.md         ← 영어 문서
+├── README.ko.md      ← 한국어 문서 (현재 파일)
+├── package.json
+└── tsconfig.json
+```
+
+### 새 언어 어댑터 추가하기
+
+파서는 현재 JS/TS 문법 휴리스틱에 의존합니다 (점 체이닝, `const`/`let`/`var`, `function`, `if`/`for`/`while`). 새 언어를 추가하려면:
+
+1. `src/parser.ts`에서 감지 헬퍼 추가 (기존 `isChaining`, `isConditional` 패턴 참고)
+2. `src/action.ts`의 `filterDiffLines`에서 새 파일 확장자 허용
+3. `src/test.ts`에 해당 언어의 diff 예시를 테스트 케이스로 추가
+4. 예시 diff를 포함해서 PR 오픈
+
+---
+
+## 라이선스
+
+MIT © [3rdflr](https://github.com/3rdflr)
+
+---
diff --git a/README.md b/README.md
index dc6ab09..f9a3297 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,5 @@
 # 📖 github-mobile-reader
 
-> **Stop squinting at code on your phone.**
 > `github-mobile-reader` transforms raw git diffs into clean, vertically-scrollable Markdown — no more pinch-zooming or swiping left and right to read a single line.
 
 [![npm version](https://img.shields.io/npm/v/github-mobile-reader.svg)](https://www.npmjs.com/package/github-mobile-reader)
@@ -15,15 +14,17 @@ GitHub's mobile web view renders code in a fixed-width monospace block. Long lin
 
 ## The Solution
 
-`github-mobile-reader` parses a git diff and produces a **Logical Flow** — a compact tree that shows *what the code does*, not just what characters changed. The result is a Markdown document that reads top-to-bottom on any screen width.
+`github-mobile-reader` parses a git diff and produces a **Logical Flow** — a compact tree that shows _what the code does_, not just what characters changed. The result is a Markdown document that reads top-to-bottom on any screen width.
 
 **Before** (raw diff, mobile web):
+
 ```
 ← swipe → swipe → swipe →
 + const result = data.map(item => item.value).filter(v => v > 10).reduce((a,b) => a+b, 0)
 ```
 
 **After** (Reader Markdown):
+
 ```
 data
  └─ map(item → value)
@@ -38,7 +39,7 @@ data
 - **Zero-dependency core** — the parser runs anywhere Node.js ≥ 18 is available
 - **Dual output format** — CJS (`require`) and ESM (`import`) with full TypeScript types
 - **GitHub Action** — drop one YAML block into any repo and get auto-generated Reader docs on every PR
-- **Tracks both sides of a diff** — shows added *and* removed code in separate sections
+- **Tracks both sides of a diff** — shows added _and_ removed code in separate sections
 - **Conservative by design** — when a pattern is ambiguous, the library shows less rather than showing something wrong
 
 ---
@@ -63,17 +64,17 @@ The parser is built on regex-based pattern matching, so it can technically recei
 
 ### Current support (v0.1)
 
-| Language | Extensions | Flow Quality | Notes |
-|----------|-----------|:------------:|-------|
-| **JavaScript** | `.js` `.mjs` `.cjs` | ✅ Full | Baseline target language |
-| **TypeScript** | `.ts` | ✅ Full | JS superset — all patterns apply |
-| **React JSX** | `.jsx` | ✅ Full | Same syntax as JS |
-| **React TSX** | `.tsx` | ✅ Full | Same syntax as TS |
-| **Next.js** | `.js` `.ts` `.jsx` `.tsx` | ✅ Full | Framework on top of JS/TS |
-| **Java** | `.java` | ⚠️ Partial (~55%) | `if/for/while` and dot-chaining work; function declarations missed (no `const/let/var`) |
-| **C#** | `.cs` | ⚠️ Partial (~35%) | LINQ chaining (`.Where().Select()`) works; `using`/`namespace`/`class` not detected |
-| **C** | `.c` `.h` | ❌ Minimal (~15%) | No matching keywords; pointer syntax (`->`, `*`) not understood |
-| **Python, Go, Rust, etc.** | — | 🔜 Planned | See roadmap below |
+| Language                   | Extensions                |   Flow Quality    | Notes                                                                                   |
+| -------------------------- | ------------------------- | :---------------: | --------------------------------------------------------------------------------------- |
+| **JavaScript**             | `.js` `.mjs` `.cjs`       |      ✅ Full      | Baseline target language                                                                |
+| **TypeScript**             | `.ts`                     |      ✅ Full      | JS superset — all patterns apply                                                        |
+| **React JSX**              | `.jsx`                    |      ✅ Full      | Same syntax as JS                                                                       |
+| **React TSX**              | `.tsx`                    |      ✅ Full      | Same syntax as TS                                                                       |
+| **Next.js**                | `.js` `.ts` `.jsx` `.tsx` |      ✅ Full      | Framework on top of JS/TS                                                               |
+| **Java**                   | `.java`                   | ⚠️ Partial (~55%) | `if/for/while` and dot-chaining work; function declarations missed (no `const/let/var`) |
+| **C#**                     | `.cs`                     | ⚠️ Partial (~35%) | LINQ chaining (`.Where().Select()`) works; `using`/`namespace`/`class` not detected     |
+| **C**                      | `.c` `.h`                 | ❌ Minimal (~15%) | No matching keywords; pointer syntax (`->`, `*`) not understood                         |
+| **Python, Go, Rust, etc.** | —                         |    🔜 Planned     | See roadmap below                                                                       |
 
 > **Note:** Java, C#, and C files are not processed by the GitHub Action by default.
 > The Action only scans `.js .jsx .ts .tsx .mjs .cjs` files ([`src/action.ts` line 66](src/action.ts)).
@@ -86,8 +87,8 @@ All four share the same underlying syntax. The parser recognises:
 - **Method chaining** — line starting with `.` after a line ending with `)` or `}`
   ```ts
   data
-    .filter(item => item.active)   // detected as P1 chain
-    .map(item => item.value)       // detected as P1 chain
+    .filter((item) => item.active) // detected as P1 chain
+    .map((item) => item.value); // detected as P1 chain
   ```
 - **Function declarations** — `const`, `let`, `var`, `function`, `async`
 - **Conditionals** — `if / else / switch`
@@ -98,12 +99,12 @@ All four share the same underlying syntax. The parser recognises:
 
 These languages use different conventions for the patterns above:
 
-| Concept | JS/TS (✅ detected) | Java / C# / C (❌ missed) |
-|---------|---------------------|--------------------------|
-| Variable declaration | `const x = …` | `int x = …` / `String x = …` |
-| Arrow callbacks | `x => x.value` | Lambdas differ per language |
-| Noise imports | `import` / `export` | `using` / `#include` / `package` |
-| Async functions | `async function foo()` | `async Task<T> Foo()` |
+| Concept              | JS/TS (✅ detected)    | Java / C# / C (❌ missed)        |
+| -------------------- | ---------------------- | -------------------------------- |
+| Variable declaration | `const x = …`          | `int x = …` / `String x = …`     |
+| Arrow callbacks      | `x => x.value`         | Lambdas differ per language      |
+| Noise imports        | `import` / `export`    | `using` / `#include` / `package` |
+| Async functions      | `async function foo()` | `async Task<T> Foo()`            |
 
 ### Roadmap — Language Adapter system (v0.2)
 
@@ -118,6 +119,7 @@ src/languages/
 ```
 
 Each adapter will declare:
+
 - Supported file extensions
 - Function-declaration detection pattern
 - Keywords to ignore (noise list)
@@ -134,13 +136,13 @@ npm install github-mobile-reader
 ```
 
 ```ts
-import { generateReaderMarkdown } from 'github-mobile-reader'
-import { execSync } from 'child_process'
+import { generateReaderMarkdown } from "github-mobile-reader";
+import { execSync } from "child_process";
 
-const diff = execSync('git diff HEAD~1', { encoding: 'utf8' })
-const markdown = generateReaderMarkdown(diff, { file: 'src/utils.ts' })
+const diff = execSync("git diff HEAD~1", { encoding: "utf8" });
+const markdown = generateReaderMarkdown(diff, { file: "src/utils.ts" });
 
-console.log(markdown)
+console.log(markdown);
 ```
 
 ---
@@ -165,8 +167,8 @@ on:
     types: [opened, synchronize, reopened]
 
 permissions:
-  contents: write        # commit the generated .md file
-  pull-requests: write   # post the PR comment
+  contents: write # commit the generated .md file
+  pull-requests: write # post the PR comment
 
 jobs:
   generate-reader:
@@ -177,7 +179,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0          # full history required for git diff
+          fetch-depth: 0 # full history required for git diff
 
       - name: Generate Reader Markdown
         uses: 3rdflr/github-mobile-reader@v1
@@ -210,11 +212,11 @@ That's it. Every subsequent PR will automatically get:
 
 ### Action Inputs
 
-| Input | Required | Default | Description |
-|-------|----------|---------|-------------|
-| `github_token` | ✅ | — | Use `${{ secrets.GITHUB_TOKEN }}` |
-| `base_branch` | ❌ | `main` | The branch the PR is merging into |
-| `output_dir` | ❌ | `docs/reader` | Directory for generated `.md` files |
+| Input          | Required | Default       | Description                         |
+| -------------- | -------- | ------------- | ----------------------------------- |
+| `github_token` | ✅       | —             | Use `${{ secrets.GITHUB_TOKEN }}`   |
+| `base_branch`  | ❌       | `main`        | The branch the PR is merging into   |
+| `output_dir`   | ❌       | `docs/reader` | Directory for generated `.md` files |
 
 ---
 
@@ -238,35 +240,38 @@ yarn add github-mobile-reader
 ### CommonJS
 
 ```js
-const { generateReaderMarkdown } = require('github-mobile-reader')
+const { generateReaderMarkdown } = require("github-mobile-reader");
 ```
 
 ### ESM / TypeScript
 
 ```ts
-import { generateReaderMarkdown, parseDiffToLogicalFlow } from 'github-mobile-reader'
+import {
+  generateReaderMarkdown,
+  parseDiffToLogicalFlow,
+} from "github-mobile-reader";
 ```
 
 ### Basic Example
 
 ```ts
-import { generateReaderMarkdown } from 'github-mobile-reader'
-import { execSync } from 'child_process'
-import { writeFileSync } from 'fs'
+import { generateReaderMarkdown } from "github-mobile-reader";
+import { execSync } from "child_process";
+import { writeFileSync } from "fs";
 
 // Get the diff for the last commit
-const diff = execSync('git diff HEAD~1 HEAD', { encoding: 'utf8' })
+const diff = execSync("git diff HEAD~1 HEAD", { encoding: "utf8" });
 
 // Generate Reader Markdown with metadata
 const markdown = generateReaderMarkdown(diff, {
-  pr: '42',
-  commit: 'a1b2c3d',
-  file: 'src/api/users.ts',
-  repo: 'my-org/my-repo',
-})
+  pr: "42",
+  commit: "a1b2c3d",
+  file: "src/api/users.ts",
+  repo: "my-org/my-repo",
+});
 
 // Write to a file or post to Slack / Discord / GitHub
-writeFileSync('reader.md', markdown, 'utf8')
+writeFileSync("reader.md", markdown, "utf8");
 ```
 
 ### Low-level API Example
@@ -274,16 +279,16 @@ writeFileSync('reader.md', markdown, 'utf8')
 If you only need the parsed tree (e.g. to build your own renderer):
 
 ```ts
-import { parseDiffToLogicalFlow, renderFlowTree } from 'github-mobile-reader'
+import { parseDiffToLogicalFlow, renderFlowTree } from "github-mobile-reader";
 
-const { root, rawCode, removedCode } = parseDiffToLogicalFlow(diff)
+const { root, rawCode, removedCode } = parseDiffToLogicalFlow(diff);
 
 // root  → FlowNode[]  (the logical tree)
 // rawCode     → string  (added lines, joined)
 // removedCode → string  (removed lines, joined)
 
-const treeLines = renderFlowTree(root)
-console.log(treeLines.join('\n'))
+const treeLines = renderFlowTree(root);
+console.log(treeLines.join("\n"));
 ```
 
 ---
@@ -304,13 +309,14 @@ A generated Reader Markdown document has four sections:
 ---
 
 ## 🧠 Logical Flow
-
 ```
+
 getData()
- └─ filter(callback)
-     └─ map(item → value)
-         └─ reduce(callback)
-```
+└─ filter(callback)
+└─ map(item → value)
+└─ reduce(callback)
+
+````
 
 ## ✅ Added Code
 
@@ -319,17 +325,19 @@ const result = getData()
   .filter(item => item.active)
   .map(item => item.value)
   .reduce((a, b) => a + b, 0)
-```
+````
 
 ## ❌ Removed Code
 
 ```typescript
-const result = getData().map(item => item.value)
+const result = getData().map((item) => item.value);
 ```
 
 ---
+
 🛠 Auto-generated by github-mobile-reader. Do not edit manually.
-```
+
+````
 
 ---
 
@@ -363,7 +371,7 @@ interface ParseResult {
   rawCode: string     // added lines joined with \n
   removedCode: string // removed lines joined with \n
 }
-```
+````
 
 ---
 
@@ -372,7 +380,7 @@ interface ParseResult {
 Converts a `FlowNode[]` tree into an array of Markdown-safe text lines.
 
 ```ts
-const lines = renderFlowTree(root)
+const lines = renderFlowTree(root);
 // [ 'getData()', ' └─ filter(callback)', ' └─ map(item → value)' ]
 ```
 
@@ -382,11 +390,11 @@ const lines = renderFlowTree(root)
 
 ```ts
 interface FlowNode {
-  type: 'root' | 'chain' | 'condition' | 'loop' | 'function' | 'call'
-  name: string
-  children: FlowNode[]
-  depth: number
-  priority: Priority
+  type: "root" | "chain" | "condition" | "loop" | "function" | "call";
+  name: string;
+  children: FlowNode[];
+  depth: number;
+  priority: Priority;
 }
 ```
 
@@ -394,13 +402,13 @@ interface FlowNode {
 
 ### `Priority` (enum)
 
-| Value | Meaning |
-|-------|---------|
-| `CHAINING = 1` | Method chains (`.map()`, `.filter()`, …) — highest priority |
-| `CONDITIONAL = 2` | `if` / `else` / `switch` blocks |
-| `LOOP = 3` | `for` / `while` loops |
-| `FUNCTION = 4` | Function declarations |
-| `OTHER = 5` | Everything else |
+| Value             | Meaning                                                     |
+| ----------------- | ----------------------------------------------------------- |
+| `CHAINING = 1`    | Method chains (`.map()`, `.filter()`, …) — highest priority |
+| `CONDITIONAL = 2` | `if` / `else` / `switch` blocks                             |
+| `LOOP = 3`        | `for` / `while` loops                                       |
+| `FUNCTION = 4`    | Function declarations                                       |
+| `OTHER = 5`       | Everything else                                             |
 
 ---
 
@@ -499,6 +507,3 @@ The parser currently relies on JS/TS syntax heuristics (dot-chaining, `const`/`l
 MIT © [3rdflr](https://github.com/3rdflr)
 
 ---
-
-> **"The era of per-device number crunching is over.
-> One logic. Every screen."**
diff --git a/src/parser.ts b/src/parser.ts
index a7c5dd4..f782b19 100644
--- a/src/parser.ts
+++ b/src/parser.ts
@@ -64,10 +64,10 @@ export function normalizeCode(lines: string[]): string[] {
   return lines
     .map(line => {
       let normalized = line;
-      normalized = normalized.replace(/;$/, '');
       normalized = normalized.replace(/\/\/.*$/, '');
       normalized = normalized.replace(/\/\*.*?\*\//, '');
       normalized = normalized.trim();
+      normalized = normalized.replace(/;$/, '');
       return normalized;
     })
     .filter(line => line.length > 0);
@@ -137,9 +137,14 @@ export function isLoop(line: string): boolean {
  * Step 9: Detect function declaration (P4)
  */
 export function isFunctionDeclaration(line: string): boolean {
+  const t = line.trim();
   return (
-    /^(function|const|let|var)\s+\w+\s*=?\s*(async\s*)?\(/.test(line.trim()) ||
-    /^(async\s+)?function\s+\w+/.test(line.trim())
+    // function foo() / async function foo()
+    /^(async\s+)?function\s+\w+/.test(t) ||
+    // const foo = () => / const foo = async () => / const foo = async (x: T) =>
+    /^(const|let|var)\s+\w+\s*=\s*(async\s*)?\(/.test(t) ||
+    // const foo = function / const foo = async function
+    /^(const|let|var)\s+\w+\s*=\s*(async\s+)?function/.test(t)
   );
 }
 
@@ -229,6 +234,22 @@ export function parseToFlowTree(lines: string[]): FlowNode[] {
       continue;
     }
 
+    // P4: function declaration — must be checked BEFORE extractRoot,
+    // because "const foo = async ..." would otherwise match extractRoot first.
+    if (isFunctionDeclaration(line)) {
+      const funcMatch = line.match(/(?:function|const|let|var)\s+(\w+)/);
+      roots.push({
+        type: 'function',
+        name: funcMatch ? `${funcMatch[1]}()` : 'function()',
+        children: [],
+        depth: relativeDepth,
+        priority: Priority.FUNCTION,
+      });
+      currentChain = null;
+      prevLine = line;
+      continue;
+    }
+
     // New root / chain start
     const root = extractRoot(line);
     if (root) {
@@ -260,16 +281,6 @@ export function parseToFlowTree(lines: string[]): FlowNode[] {
         priority: Priority.LOOP,
       });
       currentChain = null;
-    } else if (isFunctionDeclaration(line)) {
-      const funcMatch = line.match(/(?:function|const|let|var)\s+(\w+)/);
-      roots.push({
-        type: 'function',
-        name: funcMatch ? `${funcMatch[1]}()` : 'function()',
-        children: [],
-        depth: relativeDepth,
-        priority: Priority.FUNCTION,
-      });
-      currentChain = null;
     }
 
     prevLine = line;
diff --git a/src/test.ts b/src/test.ts
new file mode 100644
index 0000000..6227001
--- /dev/null
+++ b/src/test.ts
@@ -0,0 +1,373 @@
+/**
+ * github-mobile-reader — manual smoke tests
+ * Run: npx ts-node src/test.ts
+ */
+
+import {
+  filterDiffLines,
+  normalizeCode,
+  parseDiffToLogicalFlow,
+  generateReaderMarkdown,
+  renderFlowTree,
+} from './parser';
+
+// ─── ANSI helpers ────────────────────────────────────────────────────────────
+const GREEN  = (s: string) => `\x1b[32m${s}\x1b[0m`;
+const RED    = (s: string) => `\x1b[31m${s}\x1b[0m`;
+const YELLOW = (s: string) => `\x1b[33m${s}\x1b[0m`;
+const BOLD   = (s: string) => `\x1b[1m${s}\x1b[0m`;
+const DIM    = (s: string) => `\x1b[2m${s}\x1b[0m`;
+
+let passed = 0;
+let failed = 0;
+
+function assert(label: string, condition: boolean, detail?: string) {
+  if (condition) {
+    console.log(`  ${GREEN('✓')} ${label}`);
+    passed++;
+  } else {
+    console.log(`  ${RED('✗')} ${label}`);
+    if (detail) console.log(`    ${RED('→')} ${detail}`);
+    failed++;
+  }
+}
+
+function section(name: string) {
+  console.log(`\n${BOLD(YELLOW(`▶ ${name}`))}`);
+}
+
+// ─── Test fixtures ────────────────────────────────────────────────────────────
+
+const CHAINING_DIFF = `
+diff --git a/src/utils.ts b/src/utils.ts
+--- a/src/utils.ts
++++ b/src/utils.ts
+@@ -1,3 +1,7 @@
++const result = data
++  .map(item => item.value)
++  .filter(v => v > 10)
++  .reduce((a, b) => a + b, 0)
+`;
+
+const CONDITIONAL_DIFF = `
+diff --git a/src/auth.ts b/src/auth.ts
+--- a/src/auth.ts
++++ b/src/auth.ts
+@@ -0,0 +1,6 @@
++if (isValid) {
++  process(data)
++} else {
++  return fallback
++}
+`;
+
+const FUNCTION_DIFF = `
+diff --git a/src/api.ts b/src/api.ts
+--- a/src/api.ts
++++ b/src/api.ts
+@@ -0,0 +1,4 @@
++const fetchUser = async (id: string) => {
++  const res = await fetch('/api/users/' + id)
++  return res.json()
++}
+`;
+
+const MIXED_DIFF = `
+diff --git a/src/data.ts b/src/data.ts
+--- a/src/data.ts
++++ b/src/data.ts
+@@ -1,5 +1,10 @@
+-const old = legacy()
++import { api } from './api'
++const users = api.getAll()
++  .filter(u => u.active)
++  .map(u => u.name)
++
++if (users.length > 0) {
++  for (let i = 0; i < users.length; i++) {
++    process(users[i])
++  }
++}
+`;
+
+const NOISE_DIFF = `
+diff --git a/src/types.ts b/src/types.ts
+--- a/src/types.ts
++++ b/src/types.ts
+@@ -0,0 +1,5 @@
++import { Foo } from './foo'
++export type Bar = { id: string }
++interface Baz { name: string }
++console.log('debug')
++throw new Error('oops')
+`;
+
+const EMPTY_DIFF = `
+diff --git a/src/style.css b/src/style.css
+--- a/src/style.css
++++ b/src/style.css
+@@ -0,0 +1,2 @@
++.container { display: flex; }
++.item { color: red; }
+`;
+
+// ─── Test Suite 1: filterDiffLines ───────────────────────────────────────────
+
+section('filterDiffLines');
+
+const { added: chainAdded, removed: chainRemoved } = filterDiffLines(CHAINING_DIFF);
+assert(
+  'extracts added lines (+ prefix)',
+  chainAdded.length === 4,
+  `expected 4 added lines, got ${chainAdded.length}: ${JSON.stringify(chainAdded)}`
+);
+assert(
+  'skips +++ file header',
+  chainAdded.every(l => !l.startsWith('+')),
+  'a line still starts with +'
+);
+assert(
+  'removed lines empty when no - lines in diff',
+  chainRemoved.length === 0,
+  `expected 0 removed lines, got ${chainRemoved.length}`
+);
+
+const { removed: mixedRemoved } = filterDiffLines(MIXED_DIFF);
+assert(
+  'detects removed lines (- prefix)',
+  mixedRemoved.length === 1,
+  `expected 1 removed line, got ${mixedRemoved.length}: ${JSON.stringify(mixedRemoved)}`
+);
+assert(
+  'removed line content is correct',
+  mixedRemoved[0].includes('legacy()'),
+  `expected "legacy()" in removed, got: ${mixedRemoved[0]}`
+);
+
+// ─── Test Suite 2: normalizeCode ─────────────────────────────────────────────
+
+section('normalizeCode');
+
+const rawLines = [
+  'const x = foo();  // trailing comment',
+  'const y = bar();',
+  '  ',
+  '.map(i => i.val); /* inline comment */',
+];
+const normalized = normalizeCode(rawLines);
+
+assert(
+  'removes trailing semicolons',
+  !normalized.some(l => l.endsWith(';')),
+  `found semicolons in: ${JSON.stringify(normalized)}`
+);
+assert(
+  'removes // inline comments',
+  !normalized.some(l => l.includes('//')),
+  `found // in: ${JSON.stringify(normalized)}`
+);
+assert(
+  'removes /* */ block comments',
+  !normalized.some(l => l.includes('/*')),
+  `found /* in: ${JSON.stringify(normalized)}`
+);
+assert(
+  'filters out empty/whitespace-only lines',
+  !normalized.some(l => l.trim() === ''),
+  `found empty line in: ${JSON.stringify(normalized)}`
+);
+
+// ─── Test Suite 3: parseDiffToLogicalFlow — chaining ─────────────────────────
+
+section('parseDiffToLogicalFlow — method chaining');
+
+const chainResult = parseDiffToLogicalFlow(CHAINING_DIFF);
+
+assert(
+  'produces at least one root node',
+  chainResult.root.length > 0,
+  `root is empty`
+);
+assert(
+  'root node is "data" (right-hand side of assignment)',
+  chainResult.root[0]?.name === 'data',
+  `expected "data", got "${chainResult.root[0]?.name}"`
+);
+assert(
+  'root has children (chain nodes)',
+  chainResult.root[0]?.children.length > 0,
+  'no children on root node'
+);
+assert(
+  'rawCode contains the added lines',
+  chainResult.rawCode.includes('data'),
+  `rawCode missing "data": ${chainResult.rawCode.slice(0, 80)}`
+);
+
+// ─── Test Suite 4: parseDiffToLogicalFlow — conditionals ─────────────────────
+
+section('parseDiffToLogicalFlow — conditionals');
+
+const condResult = parseDiffToLogicalFlow(CONDITIONAL_DIFF);
+
+assert(
+  'detects if-block as root node',
+  condResult.root.some(n => n.type === 'condition'),
+  `no condition node found. nodes: ${JSON.stringify(condResult.root.map(n => n.type))}`
+);
+assert(
+  'condition name contains "if"',
+  condResult.root.some(n => n.name.startsWith('if')),
+  `condition name: ${condResult.root[0]?.name}`
+);
+
+// ─── Test Suite 5: parseDiffToLogicalFlow — function declaration ──────────────
+
+section('parseDiffToLogicalFlow — function declaration');
+
+const funcResult = parseDiffToLogicalFlow(FUNCTION_DIFF);
+
+assert(
+  'detects function node',
+  funcResult.root.some(n => n.type === 'function'),
+  `no function node. types: ${JSON.stringify(funcResult.root.map(n => n.type))}`
+);
+assert(
+  'function name includes "fetchUser"',
+  funcResult.root.some(n => n.name.includes('fetchUser')),
+  `function names: ${JSON.stringify(funcResult.root.map(n => n.name))}`
+);
+
+// ─── Test Suite 6: noise filtering ───────────────────────────────────────────
+
+section('noise filtering (import / export / type / interface / console / throw)');
+
+const noiseResult = parseDiffToLogicalFlow(NOISE_DIFF);
+
+assert(
+  'pure-noise diff produces empty root (nothing to show)',
+  noiseResult.root.length === 0,
+  `expected 0 root nodes, got ${noiseResult.root.length}: ${JSON.stringify(noiseResult.root.map(n => n.name))}`
+);
+// rawCode preserves all added lines verbatim (including noise) so the
+// "Actual Code" section in the output shows the real diff unchanged.
+assert(
+  'rawCode contains the original added lines (noise preserved for display)',
+  noiseResult.rawCode.includes('import') && noiseResult.rawCode.includes('interface'),
+  `rawCode: ${noiseResult.rawCode.slice(0, 80)}`
+);
+
+// ─── Test Suite 7: non-JS diff (CSS) ─────────────────────────────────────────
+
+section('non-JS diff input (CSS — graceful degradation)');
+
+const cssResult = parseDiffToLogicalFlow(EMPTY_DIFF);
+
+assert(
+  'does not throw on non-JS input',
+  true  // reaching here means no throw
+);
+assert(
+  'produces empty root for unrecognised syntax',
+  cssResult.root.length === 0,
+  `expected 0 root nodes, got ${cssResult.root.length}`
+);
+
+// ─── Test Suite 8: renderFlowTree ────────────────────────────────────────────
+
+section('renderFlowTree');
+
+const treeLines = renderFlowTree(chainResult.root);
+
+assert(
+  'returns at least one line',
+  treeLines.length > 0,
+  'renderFlowTree returned empty array'
+);
+assert(
+  'first line is the root identifier (no indent)',
+  !treeLines[0].startsWith(' '),
+  `first line has unexpected indent: "${treeLines[0]}"`
+);
+assert(
+  'child lines contain └─ connector',
+  treeLines.slice(1).some(l => l.includes('└─')),
+  `no └─ found in child lines: ${JSON.stringify(treeLines)}`
+);
+
+// ─── Test Suite 9: generateReaderMarkdown ────────────────────────────────────
+
+section('generateReaderMarkdown — full document');
+
+const md = generateReaderMarkdown(CHAINING_DIFF, {
+  pr: '42',
+  commit: 'abc1234',
+  file: 'src/utils.ts',
+  repo: '3rdflr/github-mobile-reader',
+});
+
+assert(
+  'output starts with # 📖',
+  md.startsWith('# 📖'),
+  `first chars: "${md.slice(0, 20)}"`
+);
+assert(
+  'contains PR number in metadata',
+  md.includes('#42'),
+  'PR number missing from output'
+);
+assert(
+  'contains file name in metadata',
+  md.includes('src/utils.ts'),
+  'file name missing from output'
+);
+assert(
+  'contains Logical Flow section',
+  md.includes('🧠 Logical Flow'),
+  'Logical Flow section missing'
+);
+assert(
+  'contains Added Code section',
+  md.includes('✅ Added Code'),
+  'Added Code section missing'
+);
+assert(
+  'does not contain Removed Code section when nothing removed',
+  !md.includes('❌ Removed Code'),
+  'Removed Code section appeared unexpectedly'
+);
+assert(
+  'contains auto-generated footer',
+  md.includes('Auto-generated'),
+  'footer missing'
+);
+
+// ─── Test Suite 10: generateReaderMarkdown with removed lines ─────────────────
+
+section('generateReaderMarkdown — shows removed code');
+
+const mdMixed = generateReaderMarkdown(MIXED_DIFF, { file: 'src/data.ts' });
+
+assert(
+  'contains Removed Code section when - lines exist',
+  mdMixed.includes('❌ Removed Code'),
+  'Removed Code section missing despite removed lines in diff'
+);
+assert(
+  'removed code contains the old line content',
+  mdMixed.includes('legacy()'),
+  `removed section missing "legacy()"`
+);
+
+// ─── Summary ─────────────────────────────────────────────────────────────────
+
+const total = passed + failed;
+console.log(`\n${'─'.repeat(50)}`);
+console.log(BOLD(`Results: ${GREEN(`${passed} passed`)}  ${failed > 0 ? RED(`${failed} failed`) : DIM('0 failed')}  / ${total} total`));
+
+if (failed > 0) {
+  console.log(RED('\nSome tests failed. Check output above.'));
+  process.exit(1);
+} else {
+  console.log(GREEN('\nAll tests passed! ✓'));
+}