From ee1d4277e99374b3cf1fdff2bd066c9761e244c3 Mon Sep 17 00:00:00 2001
From: Felipe Reis <felipereis@MacBook-Air-de-Felipe.local>
Date: Fri, 20 Mar 2026 13:22:16 +0000
Subject: [PATCH] docs: add build and installation instructions to README

---
 README.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 51 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 5001673..e733293 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,56 @@
 # Polyscope Chrome Extension
 
-A companion browser extension for Polyscope.
+A companion browser extension for [Polyscope](https://polyscope.dev) — connect your preview tabs to workspaces and use in-page tools like the element picker.
+
+## Requirements
+
+- [Node.js](https://nodejs.org) (v18 or later)
+- npm
+
+## Building from Source
+
+**1. Clone the repository:**
+
+```bash
+git clone https://github.com/beyondcode/polyscope-chrome.git
+cd polyscope-chrome
+```
+
+**2. Install root dependencies:**
+
+```bash
+npm install
+```
+
+**3. Install extension dependencies and build:**
+
+```bash
+cd packages/chrome-extension
+npm install
+npm run build
+```
+
+The compiled extension will be output to `packages/chrome-extension/dist/`.
+
+### Available Scripts
+
+From the `packages/chrome-extension` directory:
+
+| Command | Description |
+|---|---|
+| `npm run build` | Production build |
+| `npm run dev` | Build in watch mode (rebuilds on file changes) |
+| `npm run typecheck` | Run TypeScript type checking without emitting files |
+| `npm run package` | Build and create a `.zip` ready for the Chrome Web Store |
+
+## Installing in Chrome
+
+1. Open Chrome and navigate to `chrome://extensions`
+2. Enable **Developer mode** using the toggle in the top-right corner
+3. Click **Load unpacked**
+4. Select the `packages/chrome-extension/dist/` folder
+
+The extension icon will appear in your Chrome toolbar. Click it to toggle in-page tools on or off. You can also activate the element picker with the keyboard shortcut `Alt+Shift+P`.
 
 ## License