# Contributing

Thanks for taking the time to improve Agent Context Bridge. The project is local-first infrastructure for agent handoff, so changes should be conservative, testable, and explicit about safety boundaries.

## Development Setup

Requirements:

- Node.js `>=24`
- npm
- Linux or WSL for the primary runtime path

Install dependencies:

```bash
npm ci
```

Run verification:

```bash
npm test
npm run typecheck
npm pack --dry-run
```

In the maintainer WSL workspace, the equivalent direct commands are:

```bash
node --test tests/**/*.test.ts
node node_modules/typescript/bin/tsc --noEmit
```

## Contribution Guidelines

- Keep runtime state local to `.agent-bridge/`.
- Do not commit raw transcripts, logs, generated exports, sync bundles, secrets, keys, or local runtime state.
- Preserve default-deny behavior for remote sync and native agent writes.
- Add focused tests for parser, CLI, MCP, protocol, policy, registry, storage, or sync behavior changes.
- Use existing TypeScript ESM patterns and explicit `.ts` imports for local modules.
- Keep docs honest about scope: this bridge creates continuation context; it does not guarantee native lossless resume across agent products.

## Pull Requests

Pull requests should include:

- Purpose and user-facing impact.
- Commands or APIs changed.
- Verification output.
- Compatibility and security notes when behavior touches storage, raw evidence, policy, sync, MCP, or native write paths.

Small documentation fixes are welcome. Larger behavior changes should start with an issue that explains the target workflow and failure modes.