# Alien Reminder by Incuv8or

A menu-bar Mac app. A little branded alien flies a saucer across your screen a few minutes
before each meeting and tells you what's coming. Click-through, never steals focus, gone in
seven seconds.

Meetings come from the Calendar app on this Mac — so whatever you've already synced in
there is what it sees. No accounts, no API keys, nothing to connect.

Built for filming: there's a test-fire hotkey so you can shoot clean takes instead of
waiting for something to actually be due.

## Build and run

```bash
cd ~/Documents/mission-control-alien
./scripts/build-app.sh
open "build/Alien Reminder by Incuv8or.app"
```

A 👽 appears in the menu bar. That's the whole UI.

## Menu

| Item | What it does |
|---|---|
| **Test Fire** (`⌃⌥⌘A`) | Plays one scene right now. Works from anywhere — no need to click the menu on camera. |
| **Dismiss Reminder** (`⌃⌥⌘X`) | Clears whatever's on screen immediately. |
| **Check Now** | Forces an immediate calendar check. |
| **Settings…** | Opens the settings window. |
| **Quit** | Stops it. |

The top line of the menu is the app name, with a plain-English status underneath: how many
calendars it's watching and how much warning you've asked for.

## Dismissing a reminder early

Click the **✕** on the top-right corner of the speech bubble, or press `⌃⌥⌘X`.

The scene window is click-through so the alien never gets in your way — which also
means it can't hold a button. So the ✕ is *drawn* in the scene and *clicked* through a
small transparent panel the app parks exactly over it, sized to cover the bob of the
saucer. That panel is non-activating, so clicking it doesn't pull focus out of whatever
you're working in.

## Where the meetings come from

First launch asks for Calendar access — say yes. It reads the Calendar app on this Mac,
so it sees **everything already in there**: iCloud, any Google accounts you've added, and
any feed you subscribe to — including a ClickUp or Notion calendar. That's why a ClickUp
task can fly across your screen without this app knowing ClickUp exists.

There are no credentials of any kind: no API key, no token, no login. If a calendar is missing, add the account in
**System Settings → Internet Accounts**.

**Choosing which calendars.** Settings → *Meetings* lists every calendar on the Mac,
grouped by the account it came from — your own accounts, clients', iCloud. Untick a
client's calendar and their meetings stop showing up. Everything starts ticked on first
run, so this is opt-*out*.

Nothing ticked means nothing is announced (not "announce everything"). Calendars added
to the Mac later start unticked — tick them in Settings, or hit **All**.

All-day events and invites you've declined are always skipped.

## Settings

Everything is in **👽 → Settings…** and saves as you change it — there's no OK button to
forget. It covers which calendars to watch, how much warning you get, how often it checks, the
alien's size and colours, and whether it opens at login.

Behind it is `~/.config/mission-control-alien/config.json` — non-secret config only. You
don't need to touch it, but it's readable if you want to:

| Key | Default | Meaning |
|---|---|---|
| `calendarEnabled` | `true` | Watch meetings. |
| `meetingLeadMinutes` | `5` | Fire this long before a meeting starts. |
| `pollSeconds` | `60` | How often to check. Minimum 15. |
| `openAtLogin` | `false` | Start with macOS. |
| `sceneScale` | `1.4` | Alien size. `1.0` is subtle, `2.0` is very loud. |
| `fixedPalette` | `""` | Empty = rotate colourways. Or a name to stick to one. |
| `selectedCalendarIds` | all | Calendars being watched. Managed by the checklist. |

Adding a setting in a future version won't reset this file — unknown and missing keys
both fall back to defaults rather than failing the whole load.

## Filming it

- Set `sceneScale` to about `1.6` if you're cropping to 9:16 — the alien lands
  slightly above centre, which sits well in a vertical crop.
- Screen-record with QuickTime (**File → New Screen Recording**) and hit `⌃⌥⌘A`
  once the recording is rolling.
- The scene runs 7 seconds: glide in (1s), head pops up, line types itself, then it
  banks up and zips off right. Cut around the pop and the exit.
- It draws on whichever screen your pointer is on, so park the mouse on the display
  you're recording.

## Colours

The alien wears a different brand each time it appears — Launchpad (violet saucer, magenta
alien), Tech Queen Academy (lime/cyan saucer, pink alien), Mission Control (magenta saucer,
cyan alien). Hexes come from the real codebases, not eyeballed:
`launchpad-app/src/index.css`, `tqa-main/src/index.css`, and the `operations-centre` panel.

Settings → *The alien* → **Colours** pins it to one brand if you'd rather it didn't rotate.
The rotation position is remembered across restarts, so it doesn't reset to Launchpad every
morning.

`./.build/release/AlienHUD --snapshot <dir>` renders every colourway to a file so you can
compare them.

## Tweaking the alien

The whole scene is one CSS-animated SVG in
[`Sources/AlienHUD/Alien.swift`](Sources/AlienHUD/Alien.swift) — the beat sheet is in the
comment above `enum Alien`. Colours live separately in
[`Sources/AlienHUD/Palette.swift`](Sources/AlienHUD/Palette.swift); add an entry to
`Palette.all` and it joins the rotation and the Settings picker automatically.

To iterate without rebuilding the app, dump the scene to a file and open it in a
browser:

```bash
./.build/release/AlienHUD --dump-html > /tmp/alien.html && open /tmp/alien.html
```

`./.build/release/AlienHUD --preview` plays one scene on the real overlay and quits —
useful for checking how it sits over your actual windows. `--settings` opens the settings
window on launch.

## Launch it at login

Settings → *Startup* → **Open at login**. Move the app somewhere permanent first
(e.g. `/Applications`) or a rebuild will break the registration.

## Notes

- Ad-hoc code signed. **Rebuilding the app resets Calendar permission** — an ad-hoc
  signature is derived from the binary itself, so a new build is a new identity as far as
  macOS is concerned. It re-asks rather than silently failing; click Allow. If you ever hit
  *Don't Allow* by accident, macOS won't ask again — re-enable it in
  System Settings › Privacy & Security › Calendars.
- The app logs its calendar status at launch, so "why isn't it firing" is answerable:
  `"./build/Alien Reminder by Incuv8or.app/Contents/MacOS/AlienHUD"` in Terminal prints it.
- Each reminder fires once. If you reschedule something, it'll announce the new time.
- **There are no secrets at all** — nothing to store, rotate or leak. ClickUp integration
  was removed in favour of reading the Calendar app, which already syncs it.
- Giving it away? `SETUP-PROMPT.md` is the prompt a non-developer hands to Claude Code.
