# Repository Guidelines

## Project Structure & Module Organization

The Stream Deck plugin lives in `dynamic-deck/`; run its commands from that directory. TypeScript entrypoint and action handlers are in `src/plugin.ts` and `src/actions/`, shared logic is in `src/services/` and `src/utils/`, and Property Inspector files are in `src/ui/`. Artwork is under `imgs/`. `com.ryan-kegel.dynamic-deck.sdPlugin/` is the Stream Deck bundle; Rollup writes the plugin bundle there and copies UI and supporting assets. The nested `dynamic-deck/AGENTS.md` has detailed implementation notes; follow it when changing that project.

## Build, Test, and Development Commands

From `dynamic-deck/`:

- `npm install` installs the plugin dependencies.
- `npm run build` creates the production bundle at `com.ryan-kegel.dynamic-deck.sdPlugin/bin/plugin.js`.
- `npm run watch` rebuilds on changes and asks the Stream Deck CLI to restart the plugin.
- `node generate-assets.cjs` creates placeholder PNG assets if they are missing.

There is no configured test runner, linter, or standalone typecheck script. Use the build to check plugin compilation; do not run `tsc` directly.

## Coding Style & Naming Conventions

Use TypeScript ES modules, two-space indentation in TypeScript and Rollup configuration, and descriptive kebab-case filenames (for example, `app-monitor.ts`). Keep each Stream Deck action in its own file under `src/actions/`, and match its registered UUID to the plugin ID in the manifest. Update source files under `src/`; generated bundle files are build output. Some app discovery and window-focus features rely on Windows PowerShell and Win32 APIs.

## Testing Guidelines

No automated tests or coverage requirements are configured. For changes to plugin code, run `npm run build` from `dynamic-deck/` and inspect the generated bundle or test the action in Stream Deck when available. UI changes should be checked in the corresponding Property Inspector.

## Commit & Pull Request Guidelines

Git history currently contains only the initial commit, so no commit convention is established. Use a short, imperative summary (for example, `Fix app launcher title sync`). Pull requests should explain the behavior change, list relevant verification steps, link related issues, and include screenshots for visible Property Inspector or key-face changes.

## Configuration & Runtime Data

Keep API credentials in Stream Deck action settings, not committed files. The app tracker persists runtime statistics in `com.ryan-kegel.dynamic-deck.sdPlugin/app-stats.json`; avoid removing it unless resetting saved rankings is intended.