From 5405da4e57b9c69648919ad370102494f3932e40 Mon Sep 17 00:00:00 2001
From: Frankie Yan <frankieyan@gmail.com>
Date: Thu, 15 Jan 2026 16:15:26 -0800
Subject: [PATCH 1/2] docs: Update README for standalone package

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 82 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 022d09b..98631a2 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,88 @@
 # React Compiler Tracker
 
-While it's safe to opt out of using memoization hooks such as `useCallback` and `useMemo` in code optimized by the [React Compiler](https://react.dev/learn/react-compiler/introduction), it is easy to introduce violations that cause the compiler to bail out, leading to performance issues when values are not memoized.
+While it's safe to opt out of using memoization hooks such as `useCallback` and `useMemo` in code optimized by the [React Compiler](https://react.dev/learn/react-compiler), it is easy to introduce violations that cause the compiler to bail out, leading to performance issues when values are not memoized.
 
-Designed to run as a part of Git hooks and CI, this tool helps prevent this and progressively adopt the React Compiler by tracking and warning against newly introduced compilation errors.
+Designed to run as a part of Git hooks and CI, this tool helps prevent this and progressively adopt the React Compiler by tracking and warning against newly introduced compilation errors. It maintains a `.react-compiler-tracker.json` record file to track known compiler errors per file.
+
+## Prerequisites
+
+This tool requires the React Compiler to be configured in your project using `babel.config.js`.
+
+See the [React Compiler installation guide](https://react.dev/learn/react-compiler/installation#babel) for setup instructions.
+
+## Installation
+
+```bash
+npm install --save-dev @doist/react-compiler-tracker
+```
+
+## Usage
+
+### `--overwrite`
+
+Regenerates the entire `.react-compiler-tracker.json` by scanning all supported source files (`src/**/*.{js,jsx,ts,tsx}`). Useful for initialization or picking up changes from skipped Git hooks.
+
+```bash
+npx @doist/react-compiler-tracker --overwrite
+```
+
+### `--stage-record-file`
+
+Checks Git staged files and updates the records. Exits with code 1 if errors increase (preventing the commit), otherwise updates `.react-compiler-tracker.json` for staged files.
+
+```bash
+npx @doist/react-compiler-tracker --stage-record-file
+```
+
+### `--check-files <file1> <file2> ...`
+
+Checks specific files without updating records. Exits with code 1 if checked files show increased error counts (or new errors). Primarily for CI to ensure PRs don't introduce new compiler errors.
+
+```bash
+npx @doist/react-compiler-tracker --check-files src/components/Button.tsx src/hooks/useData.ts
+```
+
+### No flags
+
+Checks all supported source files and reports the total error count. The records file is **not** updated in this mode.
+
+```bash
+npx @doist/react-compiler-tracker
+```
+
+## Integration Examples
+
+### Git Hook with Husky
+
+Add to `.husky/pre-commit`:
+
+```bash
+npx @doist/react-compiler-tracker --stage-record-file
+```
+
+### lint-staged
+
+In `package.json`:
+
+```json
+{
+  "lint-staged": {
+    "src/**/*.{js,jsx,ts,tsx}": "npx @doist/react-compiler-tracker --check-files"
+  }
+}
+```
+
+### GitHub Actions CI
+
+```yaml
+- name: Check React Compiler violations
+  run: |
+    # Get changed files in the PR
+    FILES=$(git diff --name-only origin/main...HEAD -- '*.tsx' '*.ts' '*.jsx' '*.js' | tr '\n' ' ')
+    if [ -n "$FILES" ]; then
+      npx @doist/react-compiler-tracker --check-files $FILES
+    fi
+```
 
 ## License
 

From 96bf834dd32580ce44921aaa8494bebac9e761fe Mon Sep 17 00:00:00 2001
From: Frankie Yan <frankieyan@gmail.com>
Date: Thu, 15 Jan 2026 16:44:22 -0800
Subject: [PATCH 2/2] docs: Simplify integration examples

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 README.md | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 98631a2..463a15d 100644
--- a/README.md
+++ b/README.md
@@ -52,14 +52,6 @@ npx @doist/react-compiler-tracker
 
 ## Integration Examples
 
-### Git Hook with Husky
-
-Add to `.husky/pre-commit`:
-
-```bash
-npx @doist/react-compiler-tracker --stage-record-file
-```
-
 ### lint-staged
 
 In `package.json`:
@@ -67,7 +59,7 @@ In `package.json`:
 ```json
 {
   "lint-staged": {
-    "src/**/*.{js,jsx,ts,tsx}": "npx @doist/react-compiler-tracker --check-files"
+    "src/**/*.{js,jsx,ts,tsx}": "npx @doist/react-compiler-tracker --stage-record-file"
   }
 }
 ```