Profiles & context-aware switching

A profile is a complete menu — its own wedge layout, its own appearance config — that Swik can switch into automatically when your context changes. Connecting to your office Wi-Fi can swap to a work menu; docking your laptop to an external display can swap to a docked-desk layout; the clock crossing 5pm can swap to a personal-evening menu. This guide covers what triggers profiles can match on, how the evaluation runs, the priority order when multiple triggers compete, and the recipes that actually hold up.

What a profile holds

Each profile contains a complete snapshot of what the menu looks like and how it's configured:

• Wedges and rings — the slot layout, including any sub-menus.
• Appearance — theme, scale, dwell time, magnetism, all behavior tunings, window expansion settings.
• Trigger conditions — up to four optional conditions for auto-activation.
• Metadata — name, emoji, optional template description.

What it does not hold: the global hotkey, your Pro license, your clipboard history, or analytics. Those live outside profiles and don't change when you switch.

Setting up a profile

Open Settings → Profiles. The first profile is your current default. To add a new one:

1. Click + New profile. Pick a name (e.g. "Work"), optionally an emoji.
2. Choose how to start: from a built-in template (Work, Creative, Development, Communication, Browsing, Music), from a duplicate of an existing profile, or empty.
3. Customize the wedges in the editor — same flow as configuring your default menu.
4. Set trigger conditions in the profile detail panel (see below).

Profiles persist immediately — there's no "save" button. You can switch between profiles manually at any time via the dropdown in the Profiles tab, or let auto-switching do it.

The four trigger types

Each profile has up to four optional trigger fields. A profile activates when any of its triggers matches the current context. Setting no triggers means the profile is manual-only — it'll only activate when you switch to it explicitly.

App-foreground trigger

Activates this profile when a specific app comes to the foreground. Useful for "always show my design menu when Figma is active."

Setup: Profile detail → Auto-switch when… → pick an app. The trigger is stored as the app's bundle ID, so renaming the app doesn't break it.

Caveat: app triggers fire on app activation. If you switch back to a previously-active app within 5 seconds, the trigger doesn't re-fire. This prevents alt-tab flickering between profiles.

Wi-Fi SSID trigger

Activates when you're connected to a specific Wi-Fi network. The match is on the network name (SSID), not the BSSID — so a single SSID across multiple access points (e.g. mesh routers) all match the same profile.

Setup: Profile detail → Wi-Fi network → type the SSID exactly as it appears in your menu bar Wi-Fi list. Capitalization and spaces matter.

Implementation: Swik reads the SSID via Apple's CoreWLAN framework, falling back to networksetup -getairportnetwork en0 if CoreWLAN doesn't return a value (some macOS configurations restrict CoreWLAN). No extra permissions are needed beyond Accessibility.

Display trigger

Activates when a specific external display is connected. Built-in laptop displays are filtered out — you can't trigger on "MacBook Pro built-in screen" because that's always present. Use this for "docked-at-desk vs laptop-only" workflows.

Setup: Profile detail → External display → pick from currently-detected displays. The trigger stores the display's localized name (e.g. "Studio Display", "LG UltraFine").

Caveat: when you unplug all external displays, no display-triggered profile matches, and Swik falls through to the next trigger type or to the default profile.

Time-of-day trigger

Activates within a daily time range. Stores start and end as minutes since midnight (e.g. 9:00 = 540, 17:00 = 1020). Overnight ranges are supported (e.g. 22:00 to 6:00 wraps midnight correctly).

Setup: Profile detail → Time range → pick start and end hours. Use 24-hour format internally; the UI shows 12-hour or 24-hour based on your macOS preference.

Caveat: "Time of day" matches the system clock, not your real local time if you're traveling and haven't changed time zones. The check runs every 60 seconds, so the swap may take up to a minute to fire after the boundary crosses.

Priority — what wins when triggers compete

Multiple profiles can theoretically all match at once (you're at the office, on office Wi-Fi, with the external display plugged in, during work hours). When that happens, Swik picks one in this priority order:

Within each rank, Swik returns the first profile in your profiles list whose trigger matches — so order matters. Drag profiles up and down in Settings → Profiles to control which one wins ties.

If no profile's trigger matches the current context, the most-recently-active profile stays active. Auto-switching never leaves you in a "no profile" state.

When evaluation runs

Auto-switching listens on three independent signals plus a polling fallback. Each one fires evaluateContextTriggers() on the main thread:

Once a swap is decided, there's a 1-second debounce before the actual switch lands. This prevents flicker when context briefly changes (e.g. SSID flicks during a roam) — if the matching profile is no longer the best match by the time the debounce fires, the switch is skipped.

And one more guard: after an app-foreground trigger fires, context-trigger evaluation is suppressed for 5 seconds. This prevents app and context triggers from fighting each other when they want different profiles.

Enabling auto-switching

Auto-switch is off by default — even on Pro. The master toggle is Settings → Profiles → Auto-switch profiles based on context. Until that's on, profiles can only be switched manually via the Profiles tab dropdown.

Two reasons to leave it off: (a) you only want manual control, or (b) you only have one profile and don't need it. Once you have two or more profiles with at least one set of triggers configured, turn it on and the swaps start firing.

Recipes that hold up

Debugging — "why didn't my profile switch?"

There's no UI surface for context-trigger debugging today. To diagnose:

1. Check the master toggle — Settings → Profiles → Auto-switch profiles based on context. This is the single most common gotcha.
2. Check Pro status — context triggers are Pro-only. Settings → About should show "Pro" near the version.
3. Match SSID exactly — for Wi-Fi triggers, the SSID is case-sensitive and includes spaces. Open menu bar Wi-Fi → take the name verbatim. "My Office" ≠ "my office".
4. Verify the order — a higher-priority profile in your list might be capturing the context. Profiles → drag the one you want to win to the top.
5. Wait 60 seconds — for time triggers, the polling check runs once a minute, so a swap can lag by up to 60 seconds after a clock boundary crosses.
6. Check the 5-second cooldown — if you just app-switched, context triggers are suppressed briefly. Wait 5 seconds and recheck.
7. Look at currently-detected displays — for display triggers, plug/unplug events on some monitors can take a second to propagate. If the trigger doesn't fire after replugging, check System Settings → Displays sees the screen first.

If you've checked all of these and the swap still doesn't fire, switch the profile manually once via the Profiles dropdown. That confirms the profile is wired correctly and isolates the problem to the trigger condition specifically.

Caveats & current limits

• Multi-trigger profiles — a profile with multiple triggers (e.g. Wi-Fi="Office" AND time=9–17) currently activates if any trigger matches, not all. There's no AND logic in the current implementation. If you want the AND case, use a single trigger (the most distinctive — Wi-Fi usually wins) and accept that the same profile fires whenever you're on that network.
• No profile-specific hotkeys — every profile uses the same global hotkey. You can't have "F19 = work menu, F20 = personal menu." Use multiple triggers on multiple profiles instead.
• Profile import/export — the current Export captures the active profile's layout, hotkey, and appearance, not all profiles at once. Multi-profile export is on the roadmap.
• Time triggers don't recur — they're hour-of-day, not "every Monday at 9am." For day-of-week conditions, use an app-foreground trigger on something you typically open at that time.