# Contributing to Skills Vault

Thanks for taking the time to contribute.

Skills Vault is intentionally small. The best contributions usually keep that spirit: focused changes, clear reasoning, and tests or docs updates where behavior changes.

## Before You Start

Please read these first:

- [README.md](./README.md) for project scope and command overview
- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) for community expectations
- [SECURITY.md](./SECURITY.md) before reporting vulnerabilities

If you plan to make a substantial change, open an issue first so we can confirm the direction before code is written.

## Good First Contributions

Helpful contributions include:

- bug fixes with regression tests
- documentation improvements
- clearer CLI help text
- tighter error handling around manifest parsing and install planning
- focused UX improvements to backup, restore, doctor, and completion flows

## Local Setup

This project uses Bun only.

```sh
bun install --frozen-lockfile
```

Useful local commands:

```sh
bun run ./src/cli.ts --help
bun run ./src/cli.ts doctor
bun run test
bun run format
bun run format:check
bun run check
```

## Development Guidelines

- Use Bun for development and testing.
- Follow the existing TypeScript + ESM style.
- Prefer small helpers with explicit types over large, multi-purpose functions.
- Preserve the current command result shape: `exitCode`, `stdout`, `stderr`, optional `errorCode`, and optional `payload`.
- Reuse existing output helpers in `src/internal/cli` and path helpers in `src/internal/paths`.
- Keep comments sparse and high-signal.

## Tests and Verification

Run the full verification gate before opening a pull request:

```sh
bun run check
```

If you changed GitHub workflow files, also run:

```sh
bunx prettier --check ".github/**/*.yml"
```

When behavior changes, add or update tests for:

- CLI output and help text
- argument parsing
- install planning and concurrency behavior
- manifest parsing and building
- packaging expectations when publish behavior changes

Keep tests deterministic. Prefer injected dependencies and stubs over relying on caller machine state.

## Pull Requests

Please keep pull requests focused and include:

- a short explanation of the problem being solved
- the approach you took
- any user-facing CLI or docs changes
- the verification commands you ran

If a change affects command output, include an example of the new output in the PR description when practical.

## Reporting Bugs

Use the bug report issue template and include:

- the command you ran
- what you expected to happen
- what actually happened
- your OS and Bun version
- relevant output from `bunx skvlt doctor`

## Security Reports

Do not report security vulnerabilities in public issues or pull requests. Follow [SECURITY.md](./SECURITY.md) instead.

## Maintainer Expectations

This project is maintained on a best-effort basis. Reviews may take time, and not every feature request will fit the project scope. Clear, scoped proposals have the best chance of landing quickly.