# maCopy — Install & Usage Guide

The single living reference for **installing** and **using** maCopy.
Update this whenever a shortcut, setting, or behavior changes — this is
the doc a new user (including future-you) should be able to follow start
to finish without reading any source code.

Current version: see [CHANGELOG.md](../CHANGELOG.md). Feature backlog:
[ROADMAP.md](../ROADMAP.md).

---

## 1. Install

### Option A — you already have a built DMG/app

1. Double-click the DMG, drag **maCopy.app** into **Applications**.
2. First launch: Gatekeeper will likely warn the app is unverified
   (it's ad-hoc signed, not notarized yet — see
   [docs/SHARING.md](SHARING.md)). Right-click the app → **Open** → confirm.
3. macOS will prompt for **Accessibility** permission the first time you
   try to paste — this is required for auto-paste (`Cmd+V` simulation).
   System Settings → Privacy & Security → Accessibility → enable maCopy.
4. Look for the maCopy icon in the menu bar (top-right). No Dock icon —
   that's expected, it's a menu-bar-only app.

### Option B — build it yourself

Requirements: macOS 10.15+, [Rust](https://rustup.rs) 1.77+, Node 18+,
Xcode Command Line Tools (`xcode-select --install`).

```bash
git clone gitea@git.levkin.ca:ilia/maCopy.git
cd maCopy
npm install
npm run tauri build
open src-tauri/target/release/bundle/macos/maCopy.app
```

Copy the resulting `.app` to `/Applications` if you want **Launch at
login** to stick across rebuilds (see step 4 below).

### First-run checklist

- [ ] App icon visible in the menu bar
- [ ] Accessibility permission granted (Settings → Privacy & Security → Accessibility)
- [ ] Global hotkey `` Ctrl+` `` opens/closes the picker
- [ ] (Optional) Settings → **Launch at login** turned on

---

## 2. Everyday usage

### Opening the picker

| Action | How |
|---|---|
| Open/close | Click the menu bar icon, or press `` Ctrl+` `` |
| Dismiss | `Escape`, or click outside the window |

The hotkey is configurable — Settings → **Global hotkey** → click the
field → press your new combo.

### Pasting

| Action | How |
|---|---|
| Paste an item into the app you were just using | Click it, or select + `Enter` |
| Paste **plain** (strip formatting) | `⌥`/`Alt` + click, or right-click → **Paste plain** |
| Paste with a transform | Right-click → **Transform** → pick one |
| Paste the Nth item directly (no picker needed) | `Cmd+1` … `Cmd+9` while picker is open |
| Copy to clipboard **without** auto-pasting | Right-click → **Copy** |

**Transforms** (right-click → Transform): trim whitespace, UPPERCASE /
lowercase / Title Case, collapse whitespace/newlines, pretty-print JSON,
join to a single line. Transforms apply just before the paste — the
saved history entry is never modified.

### Selecting & managing history

| Action | How |
|---|---|
| Multi-select | `Cmd+Click` to toggle one, `Shift+Click`/`Shift+Arrow` for a range, `Cmd+A` for all |
| Paste multiple selected items (joined with newlines) | `Enter` |
| Delete | `Backspace`/`Delete` with items selected |
| Pin (keep forever, always on top) | Right-click → **Pin** / **Unpin** |
| Search | Just start typing — instant full-text search |

### What you'll see in the list

- **Images** show a small thumbnail; the full-resolution image stays in
  the database and is only loaded when you actually paste.
- **Colors** — an entry that's *exactly* a hex/rgb/hsl value (e.g.
  `#3366ff`) shows a small color chip next to it.
- **Sensitive items** (passwords, card numbers, banking details) show
  `••` and a redacted preview in the list — the real value is still
  stored and still pastes correctly. See "Privacy" below.
- **PIN** badge — pinned items, always sorted to the top, never
  auto-trimmed.
- `⌘1`–`⌘9` badges on the first nine rows — quick-paste reference.

### Settings panel

Menu bar icon → **Settings…**

| Setting | What it does |
|---|---|
| Global hotkey | Re-bind the open/close shortcut |
| Show images | Toggle thumbnail rendering in the list (off = faster on huge histories) |
| Max history | 1K / 5K / 10K / 50K entries kept before auto-trim (pinned items are exempt) |
| Window position | Near cursor, center, or a screen corner |
| Launch at login | Registers/unregisters a macOS Login Item — see [docs/LAUNCH-AT-LOGIN.md](LAUNCH-AT-LOGIN.md) |
| Pause monitoring | Tray menu checkbox — temporarily stop capturing new clipboard content |

---

## 3. Privacy — what gets captured and how

- Whitespace-only clipboard content is ignored (never saved).
- Password/card/banking-looking text is detected and **redacted in the
  list preview only** — the real value is still in the database (needed
  so paste still works) and still pastes correctly.
- No network calls, no telemetry, no accounts. Everything lives in:
  ```
  ~/Library/Application Support/maCopy/clipboard.db
  ```
- You can pause monitoring any time from the tray menu.
- Full picture, including what's *not yet* implemented (encryption at
  rest, per-app exclusions): [ROADMAP.md](../ROADMAP.md) → "Privacy & trust".

---

## 4. Troubleshooting

| Symptom | Fix |
|---|---|
| Hotkey does nothing | Settings → check it isn't a duplicate of a macOS shortcut (the old default `Cmd+\`` conflicted with window-cycling — current default is `` Ctrl+` ``) |
| Paste doesn't happen (item copies but old app doesn't receive it) | Grant **Accessibility** permission — System Settings → Privacy & Security → Accessibility → add/enable maCopy |
| App won't open ("cannot verify developer") | Right-click → Open, or `xattr -cr /Applications/maCopy.app` — see [docs/SHARING.md](SHARING.md) |
| Launch at login doesn't stick after rebuild | You're running a dev/rebuilt binary at a new path — install the `.app` under `/Applications` and re-toggle the setting |
| App feels slow / using lots of memory | Update to the latest build — see the performance notes in [README.md](../README.md#architecture); file it as a regression if it persists |

---

## 5. Where things live (quick reference)

| What | Path |
|---|---|
| App (after build) | `src-tauri/target/release/bundle/macos/maCopy.app` |
| Installer DMG | `src-tauri/target/release/bundle/dmg/maCopy_<version>_aarch64.dmg` |
| Your clipboard database | `~/Library/Application Support/maCopy/clipboard.db` |
| Source | this repo |

Sharing the app with someone else: [docs/SHARING.md](SHARING.md).
Full doc index: [docs/README.md](README.md).