ChatALL (Agent Skills)

# Repository Guidelines

## Dos and Don’ts

- **Do** align your Node.js runtime with `.nvmrc` via `nvm use` before running repo scripts.
- **Do** install dependencies with `npm install` (or `npm ci` in clean environments) so that the `postinstall` electron dependencies stay in sync.
- **Do** run `npm run lint -- src/<relative-file>` and `npx prettier --check <relative-file>` on every touched file (for example, `npm run lint -- src/main.js`).
- **Do** keep locale files in `src/i18n/locales/` and prompt catalogs in `src/prompts/` updated whenever UI strings change.
- **Don't** commit generated artifacts such as `dist_electron/` outputs or transient logs; rebuild them locally when needed.
- **Don't** change shared configuration (`package.json`, `vue.config.js`, CI workflows) or add dependencies without first confirming the impact.

## Project Structure and Module Organization

- ChatALL is a Vue 3 + Vuetify 3 desktop app packaged with Electron via `vue-cli-plugin-electron-builder`.
- `src/main.js`, `src/App.vue`: bootstraps Vuetify, Vuex, i18n, Matomo analytics, and Electron IPC wiring.
- `src/background.js`: runs the Electron main process, wiring BrowserWindow lifecycle, proxy handling, and single-instance guard.
- `src/bots/`: contains every bot connector plus registration logic in `src/bots/index.js`; use `TemplateBot.js` when adding new integrations.
- `src/components/`, `src/composables/`, `src/helpers/`: Vue components, reusable composition utilities, and helper functions.
- `src/store/`: Vuex state management modules and persistence helpers.
- `src/i18n/index.js` and `src/i18n/locales/*.json`: localization setup and language packs (fallback `en`).
- `src/prompts/`: canned prompt definitions aligned with locale files.
- `src/assets/` and `public/`: ships product icons, base HTML shell, and provider logos under `public/bots/`.
- `.github/workflows/*.yml`: CI pipelines for deploy (`deploy.yml`), release packaging (`release.yml`), and GitHub Pages sync (`static.yml`).
- `vue.config.js`: centralizes Vue CLI and Electron Builder configuration; double-check implications before changing it.
- `dist_electron/`: Electron build artifacts generated by `npm run electron:build` (ignored by version control).

## Build, Test, and Development Commands

- Scripts live in `package.json`; ensure dependencies are installed before running them.
- `npm install` / `npm ci`: install JavaScript and Electron dependencies (triggers `electron-builder install-app-deps`).
- `npm run electron:serve`: launch the Electron development build with hot reload.
- `npm run build`: produce the web build in `dist/`; used by `.github/workflows/deploy.yml`.
- `npm run electron:build`: package the desktop app for the current platform; `npm run release-<platform>` wraps platform-specific release builds.
- `npm run lint -- src/<relative-file>`: run ESLint + Prettier checks on specific files (for example, `npm run lint -- src/main.js`).
- `npx prettier --check <relative-file>`: confirm formatting per `.prettierrc.js`; `npm run format` writes the entire `src/` tree when broad formatting is necessary.
- `npm run start`: open the packaged app from the current workspace using the locally built files.

## Coding Style and Naming Conventions

- Prettier (`.prettierrc.js`) enforces semicolons, double quotes, two-space indentation, and 80-character line width; always format through Prettier rather than manual spacing.
- ESLint extends `plugin:vue/vue3-essential`, `eslint:recommended`, and `plugin:prettier/recommended`; resolve lint warnings instead of suppressing them.
- Follow existing naming: camelCase for functions/variables, PascalCase for Vue components and classes, consistent with `CONTRIBUTION.md`.
- Use the `@/` alias (configured in `jsconfig.json`) instead of deep relative paths when importing from `src/`.
- Keep code comments and implementation notes in English, and add concise comments only when logic is non-obvious.
- When adding a bot, base it on `src/bots/TemplateBot.js`, register it in `src/bots/index.js`, and update any applicable `botTags` entries.
- Update `src/i18n/locales/*.json` and matching prompt files whenever new user-facing text or actions are introduced.

## Testing Guidelines

- The project has no automated unit test suite; rely on linting, builds, and manual verification.
- Use `npm run lint -- src/<relative-file>` and `npx prettier --check <relative-file>` as fast feedback loops before committing changes.
- For functional validation, run `npm run electron:serve` to exercise UI and bot flows; when packaging logic changes, run `npm run electron:build`.
- After altering persistence (`src/store/` or migrations), launch the app to confirm data migrations and settings behave as expected.

## Commit and Pull Request Guidelines

- Follow `CONTRIBUTION.md`: keep pull requests focused, update localization files for any UI copy changes, and avoid mixing unrelated refactors with features.
- Use imperative, concise commit subjects similar to recent history (`Update dependencies`, `Remove deprecated Mixtral8x7b APIBot via Groq`), optionally with conventional prefixes (`fix:`) when appropriate.
- Run the repo’s linting and formatting commands before committing; husky’s `pre-commit` hook (`.husky/pre-commit`) already invokes `npx lint-staged` on staged Vue/JS files.
- Reference related issues or PR numbers in commit bodies when applicable, mirroring existing commits that include `(#id)` annotations.
- Include context in PR descriptions (screenshots for UI changes, reproduction steps for bug fixes) to streamline reviews.

## Safety and Permissions

- Favor minimal, file-scoped edits that respect the current formatting; never run broad reformatting across the codebase without approval.
- It is safe to read/list files, modify code under `src/`, and run targeted lint/format/build commands documented above.
- Seek confirmation before adding dependencies, altering build/release configuration, or deleting/renaming files.
- Avoid committing secrets, API keys, or personal data; configuration lives in user settings and should remain local.
- Coordinate on large architectural changes or cross-cutting refactors before implementation to prevent drift from project expectations.