# AGENTS.md: Raycast extension

## Commands
- `npm run dev` (`ray develop`, hot reload in Raycast) · `npm run build` (`ray build`) · `npm run lint` (`ray lint`; `npm run fix-lint` to autofix)
- Never run `npm run publish` unless asked.

## Manifest (`package.json`)
- Each command is listed in `commands` with `name` matching `src/<name>.tsx`, a clear `title`, `description` and `mode` (`view`, `no-view`, `menu-bar`).
- User settings go in `preferences` (extension- or command-level) with `type`, `required` and `description`; read them with `getPreferenceValues<Preferences>()`. API keys use `type: "password"`.
- Keep `icon`, `categories`, `author` and `license` valid; store linting fails otherwise.

## UI and data
- Build UI only from `@raycast/api` components (`List`, `Grid`, `Detail`, `Form`, `ActionPanel`, `Action`). No custom HTML/CSS.
- Fetch with `@raycast/utils` hooks (`useFetch`, `usePromise`, `useCachedPromise`, `useCachedState`) and pass `isLoading` to the root component. Use `keepPreviousData` and pagination options for search-as-you-type.
- Every list item has a primary action that does the obvious thing (open, copy, paste) and a sensible `ActionPanel` order; add keyboard `shortcut`s for secondary actions.
- Errors: show `showToast({ style: Toast.Style.Failure, title, message })` or `showFailureToast(error)`; never let a command crash silently. Empty states use `List.EmptyView`.
- `no-view` commands finish with `showHUD` or a toast; `menu-bar` commands keep work short and cached.
- Store small data with `LocalStorage` or `Cache`; never write secrets to them. OAuth via `OAuth.PKCEClient` or the utils OAuth helpers.
- Don't run shell commands or AppleScript unless the feature needs it; quote all arguments.

## Done when
`ray lint` and `ray build` pass, and each changed command was opened with `npm run dev` (say if Raycast wasn't available to check).