> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bugspray.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Contribute to Bugspray

> Work from current source, preserve user data and make changes reviewable.

Start with the repository's [CONTRIBUTING.md](https://github.com/SynclyUS/bugspray/blob/main/CONTRIBUTING.md), [AGENTS.md](https://github.com/SynclyUS/bugspray/blob/main/AGENTS.md) and [CONCEPTS.md](https://github.com/SynclyUS/bugspray/blob/main/CONCEPTS.md). Executable source, tests and live behavior are authoritative when prose differs.

## Start in a task worktree

Fetch origin and base a separate task branch/worktree on current `origin/main`. Preserve edits you did not make. Before implementation:

```sh theme={null}
git rev-parse --show-toplevel
git status --short --branch
git worktree list
git branch --show-current
pnpm install --frozen-lockfile
```

Use a distinct `QA_SUITE_DATA_DIR` and free ports. Never copy customer data into a fixture or point two processes at the same writable database. Shared contracts belong in `apps/shared`, server/persistence in `apps/server`, UI in `apps/web` and public documentation in `docs-site/`. Keep existing `docs/*.md` operational references working. Do not modify vendored distributions.

## Validate the change you made

Runtime changes use the required repository checks:

```sh theme={null}
pnpm exec playwright install chromium
pnpm build
pnpm test
pnpm duplicate:check
```

Full checks include browser and local D1 behavior; recording paths may also need ffmpeg/Xvfb. Use focused checks while iterating and disclose unrun requirements. Documentation-only changes need link/example verification and the docs checks below; they do not require the entire application test suite.

## Edit and preview this site

Use Node 22.19 and the isolated docs toolchain. From the repository root:

```sh theme={null}
cd docs-site/tooling
pnpm install --frozen-lockfile
pnpm run validate
pnpm run links
pnpm run dev
```

The preview opens at `http://localhost:3012`. To select another free port, run `cd .. && ./tooling/node_modules/.bin/mint dev --no-open --port 3013` from the tooling directory.

The docs-only workspace pins Mintlify CLI `4.2.1204` with hoisted dependencies because this release's scraping dependency cannot resolve validation under isolated `pnpm dlx`. The app package and lockfile remain separate. Build scripts are enabled only for esbuild/sharp; telemetry-install and optional keychain builds are disabled. See [Mintlify's CLI reference](https://www.mintlify.com/docs/cli/commands) before updating. No global install or hosted account is required.

Use current `docs.json`, root-relative site links and MDX pages. Local preview starts no hosted publication.

Run `python3 tooling/check.py` from `docs-site/` for navigation, local asset/link and repository-source target checks. Verify actual preview pages in light/dark and narrow layouts before review. Tooling and examples live under this docs root to avoid changing app dependencies.

## Submit a reviewable change

Keep commits focused and explain behavior, validation and limitations. Push your task branch and open a PR against main. Do not merge or deploy as part of ordinary contribution. Runtime UI changes additionally need the exact-head, credential-free preview required by AGENTS.md.

GitHub Issues are currently disabled. Discuss substantial changes through an existing maintainer channel or the [organization contact](https://github.com/SynclyUS). Do not use Bugspray's consumer feedback MCP for work in this repository. Follow [security reporting](https://github.com/SynclyUS/bugspray/blob/main/SECURITY.md) and [community conduct](https://github.com/SynclyUS/bugspray/blob/main/CODE_OF_CONDUCT.md).

## Release decisions remain with owners

The project license and independent AgentFlow redistribution/access decisions are unresolved. A docs PR does not authorize public release, repository visibility changes, hosted publication or a support commitment. Use the existing [release policy](https://github.com/SynclyUS/bugspray/blob/main/docs/releases.md) for the reviewed source export, notices, maintenance ownership and runtime/container acceptance.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.