# Install Patchpin in Chrome

1. Download **patchpin-chrome.zip** and extract it into a permanent folder such as `Documents/Patchpin`. Keep the folder: Chrome loads the extension from it.
2. Open **chrome://extensions** in Chrome.
3. Enable **Developer mode** at the top right.
4. Click **Load unpacked** and choose the extracted folder containing **manifest.json**. Do not choose the ZIP file itself or the outer GitHub artifact folder.
5. Open the puzzle-piece menu in Chrome’s toolbar and pin **Patchpin**.
6. Visit a normal website, click the Patchpin icon, and choose **Select element**. The keyboard shortcut is **Alt + Shift + P** (Chrome’s extension shortcuts page lets you change it).

The welcome page opens after installation. You can open it again from Patchpin’s **Settings** link or Chrome’s extension Details → Extension options.

## Activate your purchase

Open **Settings**, paste your complete `PP1.…` license key, and click **Activate license**. Keys are verified locally; no account or online activation is required. Keep your key for reinstalls. The personal edition is already unlocked.

## Make your first change

Select a heading, enter a replacement, and click **Add change**. The page shows a live preview while you type. Styled headings and text with links show separate text-part fields, preserving their formatting. Press Cmd/Ctrl+Enter or click Add change to save. Select a button and add another edit. Capture an element or viewport if useful. **Copy AI prompt**, or **Export ZIP** with a lifetime license to include screenshots. Paste the prompt into your coding agent and attach the PNGs.

Closing Patchpin restores previews. Refreshing restores the website too, while your draft stays saved.

## Update

Replace the files in the same unpacked folder with the new release, then click **Reload** on Patchpin in `chrome://extensions` and refresh any websites where Patchpin was open. Keeping the folder path preserves the unpacked extension’s identity and local data. Export important drafts before moving the folder or uninstalling.

## Iterate from source

Run `pnpm dev` in the Patchpin repository to rebuild a personal development edition whenever source files change. Load the repository’s `dev-extension/` directory once as unpacked, or run `pnpm dev --sync-to "/path/to/the/folder/you/already/loaded"` to update your existing installation without changing its identity or drafts.

After each rebuild, click **Reload** on Patchpin in `chrome://extensions`, refresh the website you are editing, and reopen Patchpin. You do not need to download or extract a new ZIP for each change. The source watcher rebuilds files; it does not automatically reload browser tabs or Chrome's extension runtime.

## Troubleshooting

- **A “!” badge appears:** Chrome blocks extensions on browser settings, the Web Store, and other protected pages. Try a normal HTTP or HTTPS website.
- **Clipboard unavailable:** Patchpin downloads the Markdown prompt when copying is blocked.
- **An element’s text cannot be edited:** it is a layout container rather than inline text. Select its heading, paragraph, or text child. Styled spans and links can be edited using the text-part fields.
- **The screenshot is partial:** element capture crops to what is visible. Capture its parent/section or use full-page capture for ordinary scrolling pages.
- **Local storage is full:** export your drafts, then delete old screenshots or saved pages in Settings.
- **Another tab updated the draft:** close and reopen Patchpin to load the latest version.

A ZIP is an unpacked installation or Chrome Web Store upload artifact. This is not a signed auto-installer; Chrome Web Store publication is a separate step.

## Capture precisely

Screenshot buttons are visible in the change set. **Pick an element** captures exactly its visible bounds, including small text spans or buttons. **Drag an area** captures a rectangle: drag in either direction and release to save. Escape or Cancel exits selection. The composer shrinks while picking and disappears from every screenshot. **Full-page screenshot** stays visible alongside Viewport.

## Optional AI text replacements

Open Settings and follow **Connect your local AI tool**, or see [AI_SETUP.md](AI_SETUP.md). Suggestions preserve styled text parts and links. Choose **Use option**, edit further if needed, then **Add change**. Copy/export needs no AI connection. **Open prompt in Cursor** uses a desktop prompt link for prompts under 10,000 encoded characters. Screenshots must be attached separately.