# Vela setup guide

Vela is a native macOS control surface for launching commands, searching clipboard
history, controlling windows, and expanding snippets. Its behavior is defined in
one local JavaScript configuration file. This guide is the canonical setup
procedure for people and LLM assistants.

## Prerequisites

- macOS 14 or later on Apple silicon.
- Install the Apple-notarized DMG from [the latest Vela release](https://github.com/tubasasakunn/vela/releases/latest),
  then drag Vela to Applications. Homebrew is also supported:

  ```sh
  brew install tubasasakunn/tap/vela
  ```

## First-time setup

1. Ask the person where they want Vela's configuration folder. Use
   `~/.config/vela` when they have no preference.
2. Run the helper from the installed app. The directory argument must be an
   absolute path:

   ```sh
   /Applications/Vela.app/Contents/Helpers/vela init --directory "<configuration-folder>"
   ```

3. Do not propose or edit settings until that command finishes. It creates (or
   preserves) `vela.js`, `AGENT.md`, and
   `.agent/skills/vela-configuration/` in the configuration folder.
4. Before suggesting a configuration, read `AGENT.md`,
   `.agent/skills/vela-configuration/SKILL.md`, and its
   `references/vela-js-api.md`. If the assistant cannot access the folder,
   ask the person to attach those files to the conversation.
5. Ask about frequently opened apps, desired shortcuts, snippets, and window
   actions. Explain the proposed changes and any possible shortcut conflicts,
   then obtain confirmation before editing `vela.js`.
6. Validate and activate the approved configuration:

   ```sh
   /Applications/Vela.app/Contents/Helpers/vela check
   /Applications/Vela.app/Contents/Helpers/vela reload
   ```

## Permissions

Use the guided command after configuration. It shows current status, requests
only missing permissions, and continues after macOS authorization:

```sh
/Applications/Vela.app/Contents/Helpers/vela permissions setup
```

Do not reset existing macOS permissions. If macOS no longer presents a prompt,
use `vela permissions open <name>` to open the relevant System Settings page.

## Safety and scope

- Keep settings in `vela.js`; Vela validates them before the running app adopts
  them.
- Use only the documented Vela API in the generated configuration skill.
- Do not add filesystem, network, or environment access to the configuration.
- Preserve existing user settings unless the person explicitly asks to change
  them.