accounted/CONTRIBUTING.md

# Contributing to Accounted

Thank you for your interest in contributing to Accounted. This guide covers the development workflow, coding standards, and submission process.

Everyone interacting in the project is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).

## Getting Started

1. Fork the repository and clone your fork
2. Install dependencies: `npm install`
3. Start the dev server: `npm run dev`
4. Run tests: `npm test`

## Supabase Setup

You need a Supabase project for local development:

1. Create a free project at [supabase.com](https://supabase.com)
2. Run all migrations from `supabase/migrations/` against your project
3. Copy `.env.example` to `.env` and fill in your Supabase credentials:
   - `NEXT_PUBLIC_SUPABASE_URL`
   - `NEXT_PUBLIC_SUPABASE_ANON_KEY`
   - `SUPABASE_SERVICE_ROLE_KEY`

## Development Workflow

1. Create a branch from `main` with a descriptive name
2. Make your changes following the code style below
3. Run the full check suite before submitting:

```bash
npm run lint
npm test
npm run build
```

4. Commit using [Conventional Commits](https://www.conventionalcommits.org/):
   - `feat:` new feature
   - `fix:` bug fix
   - `refactor:` code restructuring
   - `test:` adding or updating tests
   - `docs:` documentation changes

## DCO Sign-Off

All commits must include a `Signed-off-by` line certifying that you have the right to submit the contribution under the project's license. This is the [Developer Certificate of Origin](https://developercertificate.org/) (DCO).

Add the sign-off automatically with `git commit -s`:

```
feat: add VAT report export

Signed-off-by: Your Name <your.email@example.com>
```

If you forget, you can amend: `git commit --amend -s`.

## Pull Requests

- Keep PRs focused on a single change
- Include a clear description of what and why
- Ensure CI passes (the core build resets extensions to empty, so core code must compile standalone)
- Link related issues if applicable

## Extension Development

See [ARCHITECTURE.md](ARCHITECTURE.md) and [docs/EXTENSIONS.md](docs/EXTENSIONS.md) for the full extension architecture. Quick start:

```bash
npx tsx scripts/create-extension.ts --name my-ext --sector general --category operations --description "..."
```

Then add `"my-ext"` to `extensions.config.json` and run `npm run setup:extensions`.

Constraints:
- Extensions cannot use dynamic imports (Next.js bundling requirement)
- Core must build and run with zero extensions enabled
- Never import from `@/extensions/` in core code

## Community Registry

The registry at [gnubok.se/community/registry](https://www.gnubok.se/community/registry) (skills, MCP servers, workflows and apps built on Accounted) is sourced from the [`registry/`](registry/) directory in this repo. To list something you built, add an MDX entry there by PR; see [registry/README.md](registry/README.md) for the format and run `npm run validate:registry` for the local check. No code changes needed.

## What Not to Do

- **Don't modify enforcement triggers** in migration 017 (legally required for Swedish accounting law)
- **Don't insert directly into journal tables** -- use the engine functions in `lib/bookkeeping/engine.ts`
- **Don't break the core/extension boundary** -- core must compile standalone without extensions
- **Don't delete posted journal entries** -- use storno reversal via `reverseEntry()`

## Code Style

- TypeScript strict mode, no `any` unless unavoidable
- English for all code, comments, and commit messages
- `Math.round(x * 100) / 100` for monetary calculations, never `toFixed()`
- Account numbers are strings (`'1930'`, not `1930`)
- All shared types go in `types/index.ts`

## Questions?

Open a discussion or issue on GitHub. For security vulnerabilities, see [SECURITY.md](SECURITY.md).