# Repository Guidelines

## Project Structure & Module Organization

- `src/`: React + TypeScript desktop UI (views, components, hooks, API helpers).
- `src/views/LibraryView.tsx`: primary Library maintenance surface (CRUD-style session list/actions). Start here for Library changes.
- `src-tauri/`: Rust/Tauri host app and native commands (`src-tauri/src/*.rs`).
- `python_sidecar/`: FastAPI sidecar for event processing, analysis, export, and upload.
- `widget/`: embeddable player bundle built with Vite.
- `scripts/dev.sh`: local launcher that boots sidecar + Tauri together.

## Build, Test, and Development Commands

- `npm install`: install frontend/Tauri JS dependencies.
- `cd python_sidecar && python3 -m venv .venv && source .venv/bin/activate && pip install -e '.[dev]'`: set up sidecar dev env.
- `./scripts/dev.sh`: run full desktop dev stack (sidecar on `127.0.0.1:8765` + Tauri app).
- `npm run build`: TypeScript compile + Vite build.
- `npm run lint`: run ESLint on TS/TSX code.
- `npm run format:check` / `npm run format`: verify or apply Prettier formatting.
- `npm run tauri:dev` / `npm run tauri:build`: run or package the desktop app.
- `cargo test --manifest-path src-tauri/Cargo.toml`: run Rust tests.
- `pre-commit install && pre-commit run --all-files`: enable and verify local commit hooks.

## Coding Style & Naming Conventions

- TypeScript/React: 4-space indentation (Prettier-enforced), `PascalCase` components, `camelCase` variables/hooks.
- Python: Ruff + strict Mypy (`python_sidecar/pyproject.toml`), max line length 100, type annotations required.
- Rust: idiomatic `snake_case` for functions/modules, `CamelCase` for types; keep Tauri commands small and composable.
- Keep file names descriptive by domain (`LibraryView.tsx`, `python_bridge.rs`, `analysis.py`).

## Testing Guidelines

- Python sidecar: run `pytest`, `ruff check .`, and `mypy .` from `python_sidecar/` before PRs.
- Rust: run `cargo test --manifest-path src-tauri/Cargo.toml` for backend changes.
- Frontend: at minimum run `npm run build` to catch type/runtime build regressions.
- Name Python tests `test_*.py`; keep integration scenarios separated from unit tests.

## Commit & Pull Request Guidelines

- Follow Conventional Commit style seen in history: `feat(...)`, `fix(...)`, `chore(...)`.
- Keep commits scoped (UI, sidecar, Rust host changes separated when practical).
- PRs should include: purpose, affected paths, local verification commands, and screenshots/video for UI changes.
- Link related issues and note config/permission impacts (screen recording, FFmpeg, API keys).

## Security & Configuration Notes

- Never commit secrets; use environment variables (for example `OPENAI_API_KEY`).
- Validate macOS permission-sensitive flows (screen recording, accessibility) when touching capture logic.

## Skills

A skill is a set of local instructions to follow that is stored in a `SKILL.md` file. Below is the list of skills that can be used. Each entry includes a name, description, and file path so you can open the source for full instructions when using a specific skill.

### Available skills

- skill-creator: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Codex's capabilities with specialized knowledge, workflows, or tool integrations. (file: /Users/farman/.codex/skills/.system/skill-creator/SKILL.md)
- skill-installer: Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos). (file: /Users/farman/.codex/skills/.system/skill-installer/SKILL.md)

### How to use skills

- Discovery: The list above is the skills available in this session (name + description + file path). Skill bodies live on disk at the listed paths.
- Trigger rules: If the user names a skill (with `$SkillName` or plain text) OR the task clearly matches a skill's description shown above, you must use that skill for that turn. Multiple mentions mean use them all. Do not carry skills across turns unless re-mentioned.
- Missing/blocked: If a named skill isn't in the list or the path can't be read, say so briefly and continue with the best fallback.
- How to use a skill (progressive disclosure):
  1) After deciding to use a skill, open its `SKILL.md`. Read only enough to follow the workflow.
  2) When `SKILL.md` references relative paths (e.g., `scripts/foo.py`), resolve them relative to the skill directory listed above first, and only consider other paths if needed.
  3) If `SKILL.md` points to extra folders such as `references/`, load only the specific files needed for the request; don't bulk-load everything.
  4) If `scripts/` exist, prefer running or patching them instead of retyping large code blocks.
  5) If `assets/` or templates exist, reuse them instead of recreating from scratch.
- Coordination and sequencing:
  - If multiple skills apply, choose the minimal set that covers the request and state the order you'll use them.
  - Announce which skill(s) you're using and why (one short line). If you skip an obvious skill, say why.
- Context hygiene:
  - Keep context small: summarize long sections instead of pasting them; only load extra files when needed.
  - Avoid deep reference-chasing: prefer opening only files directly linked from `SKILL.md` unless you're blocked.
  - When variants exist (frameworks, providers, domains), pick only the relevant reference file(s) and note that choice.
- Safety and fallback: If a skill can't be applied cleanly (missing files, unclear instructions), state the issue, pick the next-best approach, and continue.