# Repository Guidelines

## Project Structure & Module Organization
- Core entry: `index.js` exports the default `ssb-server` instance. CLI entry: `bin.js` (exposed as `ssb-server` / `sbot`).
- Library helpers live in `lib/` (CLI aliases, progress, validation). Prefer adding new shared logic here rather than in `bin.js`.
- Tests live in `test/` and are plain Node scripts (mostly using `tape`). Use descriptive filenames like `caps.js`, `defaults.js`.
- System integration artifacts live in `systemd/`. Keep them minimal and distro-agnostic.
- Do not edit `node_modules/`; send fixes upstream and update dependencies instead.

## Build, Test, and Development Commands
- `npm install` – install dependencies (run once before development).
- `npm test` – run the full test suite (`node test/*.js`).
- `npm run test:pretty` – run tests with `tap-spec` output.
- `npm run coverage` – generate coverage via `nyc` (outputs `coverage/`).
- `npm start` – run the CLI locally (`node bin start`), equivalent to `ssb-server start` when installed globally.

## Coding Style & Naming Conventions
- Language: Node.js, CommonJS (`require`, `module.exports`), callback-style APIs and pull-streams.
- Indentation: 2 spaces, no hard tabs. Prefer single quotes and omit semicolons (match existing files).
- Use `var` and classic function declarations in existing modules; introduce `const`/`let` only when touching newer code paths consistently.
- File and symbol names: camelCase for functions/variables, kebab-case for CLI commands, lowerCamelCase JSON/config keys.

## Testing Guidelines
- Tests use `tape`. Structure as `test('description', function (t) { ... })` and ensure all async work calls `t.end()` or ends via plan.
- To run a single test file: `node test/<file>.js`.
- Prefer deterministic tests using temporary directories under `/tmp/` and `process.env.ssb_appname = 'test'`, as existing tests do.
- When adding features or fixing bugs, include or update tests to cover the behavior; check `npm run coverage` if changes are large.

## Commit & Pull Request Guidelines
- Commit messages: short, imperative summaries (e.g. `Update caps defaults`, `Fix bin.js IPv6 handling`), with issue/PR references like `(#762)` when applicable.
- Pull requests should explain the motivation, outline key changes, list how to reproduce and verify, and state which tests were run.
- For behavioral or CLI changes, update `README.md` and add small usage examples where helpful.

## Security & Configuration Tips
- Never commit secrets, private keys, or real-world `~/.ssb` data. Use throwaway keys and caps in tests and examples.
- Be conservative with network- and replication-related changes; prefer opt-in configuration flags and document defaults clearly.