# Contributing

> Where to ask for help with the open-source engine, how to report a bug or send a change, and the terms a contribution is accepted under, including the sign-off on every commit.

Applies to: the Sypnia engine (open source, self-hosted). Status: at launch.  
Source: https://docs.sypnia.com/licensing/contributing/

For agents: How to contribute to Sypnia's open-source parts (engine, Console, SDKs, @sypnia/mcp, skills, docs): where to ask questions and report bugs, what a good report contains, the docs-first flow of a change, and the terms: contributions are licensed under the repository's own licence (AGPL-3.0, MIT or CC BY 4.0), authors keep their copyright, there is no CLA, and every commit must carry a Developer Certificate of Origin sign-off (git commit -s).

**\[Engine]** This page is for anyone who wants help with the open-source parts of Sypnia, or wants to improve them: the engine and its Console, the SDKs, `@sypnia/mcp`, the agent skills and these docs. The Sypnia Cloud app is not open source and takes no contributions; for Sypnia Cloud, see [Support](https://docs.sypnia.com/cloud/support).

> **Note: The repositories open at launch**
>
> The engine is written documentation-first, so today the contract exists and the public repositories do not yet. This page describes how contributing works once they open. The terms below are a proposal to be confirmed with the licences.

## Where things live

| What                                                          | Repository                                                                  | Licence   |
| ------------------------------------------------------------- | --------------------------------------------------------------------------- | --------- |
| The engine, the Console, the specifications, the deploy files | `github.com/sypnia/sypnia`                                                  | AGPL-3.0  |
| The agent skills                                              | [`github.com/sypnia/skills`](https://github.com/sypnia/skills)              | MIT       |
| The SDKs and `@sypnia/mcp`                                    | Linked from each package's page on npm                                      | MIT       |
| These docs                                                    | Linked from «Edit this page» at the bottom of every page, once it is public | CC BY 4.0 |

## Ask a question, report a bug

Help for the open-source engine is given by the community, in the open, in the engine's repository. We read it and answer when we can; there is no promised response time.

| You have                                     | Where                                                                                                                             |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| A question about running or using the engine | The repository's discussions                                                                                                      |
| A bug                                        | The repository's issue tracker                                                                                                    |
| An idea for a change                         | An issue, before any code                                                                                                         |
| A security problem                           | **Not in public.** See [Report a security problem](https://docs.sypnia.com/privacy/security-practices#report-a-security-problem). |

A bug report that gets fixed fast has:

1. **The version**: the output of `sypnia version`, and the SDK's name and version.
2. **The setup**: the output of `sypnia doctor`. It prints no secrets.
3. **What you expected and what happened**, one sentence each.
4. **How to repeat it.** For a wrong number or a wrong grouping, the batch of events that shows it is the best report there is.

Never paste an API token or the root token. An ingest key is public and fine to share.

## Send a change

Sypnia is built documentation-first, and a change follows the same order. The full flow, with the checks that run on every pull request, is in [The codebase](https://docs.sypnia.com/architecture/codebase#how-a-contribution-flows). In short:

### 1. Open an issue first

Say what should change and why. It saves you from writing something that cannot be merged. Some changes are decisions, not code, and are settled in an issue: a new required service, a change that would split existing problems, an integration that sends alerts to a chat product.

### 2. Change the docs before the code

If behaviour changes, the page that describes it changes in the same pull request, and so does the file in `spec/` when an endpoint, an event, a setting or a command moves. A behaviour change without its docs change is not reviewed.

### 3. Write the code with its tests, and sign your commits

```bash
git commit -s -m "Fix the p75 of an hour with no views"
```

**You should see:**

The commit message ends with your sign-off:

```text
Fix the p75 of an hour with no views

Signed-off-by: Ana Ruiz <ana@example.com>
```

### 4. Open the pull request

The automatic checks must pass. A maintainer reviews, may ask for changes, and merges.

Small fixes to the docs, such as a typo, a broken link or a clearer sentence, need no issue. Every page has an English and a Spanish version; change both, or say in the pull request that the other is missing, and someone will write it.

## The terms of a contribution

They are short on purpose.

- **Your contribution takes the licence of the repository it goes into**: AGPL-3.0 for the engine and the Console, MIT for the SDKs, `@sypnia/mcp` and the skills, CC BY 4.0 for the docs. What comes in is licensed exactly like what goes out.
- **You keep your copyright.** You do not hand it to us.
- **There is no contributor licence agreement to sign.** Instead, every commit carries a sign-off.

### The sign-off

The line `Signed-off-by: Your Name <you@example.com>` at the end of a commit message says that you agree to the [Developer Certificate of Origin](https://developercertificate.org/), version 1.1. In plain words, you state that:

1. you wrote the change, or you have the right to submit it under the repository's licence;
2. if it builds on someone else's work, that work's licence allows it;
3. you know the contribution is public and is kept, with your name and e-mail address, in the project's history.

How to do it:

| To                                    | Run                               |
| ------------------------------------- | --------------------------------- |
| Sign a commit as you make it          | `git commit -s`                   |
| Add the sign-off to your last commit  | `git commit --amend -s --no-edit` |
| Add it to every commit of your branch | `git rebase --signoff main`       |

Use your name, or the name you are known by, and an address that reaches you. A check on every pull request refuses commits without a sign-off.

### What this means for you and for us

- Nobody, including us, can take your contribution and put it under another licence. The engine stays AGPL for everyone. Sypnia Cloud runs the engine as published.
- If your employer owns what you write, make sure you are allowed to contribute it. The sign-off is you saying that you are.
- **Code written with the help of an AI tool** is welcome on the same terms. You sign off on it like on any other change, so read it and make sure you may submit it.
- **Code copied from elsewhere** must come under a licence that fits the repository's, and the pull request must say where it comes from.

## What a maintainer looks for

Before style or taste, the rules of the engine: every new write can run twice safely, nothing takes a project as a bare string, no input can make the engine panic, and a migration only adds. They are explained, with the code, in [The codebase](https://docs.sypnia.com/architecture/codebase).

Be specific and be kind. People read these threads in their spare time, in their second language.

## Related
