diff --git a/README.md b/README.md
new file mode 100644
index 00000000..b9553c0e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,95 @@
+# yt2press
+
+A tool to convert YouTube videos into press-ready markdown documents with timestamped screenshots.
+
+## How to Use
+
+### Step 1: Prepare Your Video
+
+Download or place a video file in the `/docs/public` directory.
+
+### Step 2: Create a Markdown File
+
+Create a markdown file in `/docs` directory. The filename should match the video filename with `[xxx]` removed.
+
+For example:
+- Video file: `my-video[abc123].mp4` → Markdown file: `my-video.md`
+- Video file: `presentation.mp4` → Markdown file: `presentation.md`
+
+The markdown file content can be:
+
+**Option A: YAML Frontmatter (for auto-generating timestamps)**
+```yaml
+---
+interval: 5
+dedup: true
+---
+
+Your content here...
+```
+
+- `interval`: (Optional) Interval in seconds to auto-generate timestamps
+- `dedup`: (Optional) Set to `true` to remove similar screenshots (defaults to 0.005), or specify a custom threshold value
+
+**Option B: Manual Timestamps**
+```markdown
+---
+---
+
+Content with timestamps...
+
+1:30
+
+2:45
+
+5:00
+```
+
+Timestamps should be in `M:SS` or `MM:SS` format on their own line. They will be converted to timestamped screenshot references.
+
+### Step 3: Start the Development Server
+
+Run the following command in the project directory:
+
+```bash
+pnpm run dev
+```
+
+This starts the VitePress development server and WebSocket server for communication.
+
+### Step 4: Use the Downloader Interface
+
+1. Open the VitePress website in your browser
+2. Find the downloader component
+3. Enter your video filename in the textbox
+4. Press Enter or Submit
+
+The app will:
+- Load the video
+- Extract screenshots at specified timestamps
+- Replace timestamp lines with embedded screenshot images
+- Save the updated markdown file
+
+## Project Structure
+
+```
+docs/                          # VitePress documentation root
+  .vitepress/
+    theme/
+      components/
+        Downloader.vue        # Vue component for the downloader interface
+  public/                      # Video storage directory
+  *.md                         # Markdown files with content
+  [video-folder]/             # Screenshot folders (auto-generated)
+    *.png                      # Timestamped screenshots
+server.js                       # WebSocket server for handling downloads
+group-similar.js               # Script for deduplicating similar screenshots
+```
+
+## Dependencies
+
+- Node.js and pnpm
+- VitePress for static site generation
+- WebSocket for real-time communication between browser and server
+- gray-matter for parsing YAML frontmatter
+- Sharp for image processing (screenshot manipulation)