> For the complete documentation index, see [llms.txt](https://cjay-1.gitbook.io/cjay-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cjay-1.gitbook.io/cjay-docs/contributing.md).

# Contributing

Each repo has its own `CONTRIBUTING.md` with the specifics. This page is the shared picture.

## Repos and where work goes

| Change is about…                                                          | Repo                     |
| ------------------------------------------------------------------------- | ------------------------ |
| Contract logic, state machine, on-chain auth, events                      | `heirloom-contracts`     |
| Endpoints, encryption, archive, messages, reminders, unsigned-XDR builder | `heirloom-api`           |
| Screens, flows, wallet integration, copy, design                          | `heirloom-web`           |
| These docs                                                                | `heirloom-web` (`docs/`) |

A change that spans repos (e.g. a new contract function plus the UI to call it) gets a coordinated issue in each, with an explicit **"Depends on"** cross-reference. Ship in dependency order — contract deployed first, then API, then web.

## Workflow (all repos)

1. `main` is protected. Branch, commit, push, open a PR.
2. One logical change per PR. One logical unit per commit; push after each.
3. Conventional commits: `type(scope): description`.
4. CI must be green before review:
   * `heirloom-contracts`: `fmt`, `clippy`, `test`, `build`
   * `heirloom-api`: `ci` (tsc, eslint `--max-warnings 0`, jest, build)
   * `heirloom-web`: `ci` (tsc, next lint, next build)
5. New behaviour ships with tests. Don't weaken a test to make CI pass.

## Non-negotiables

* **Contracts:** no `unwrap`/`panic` outside tests, no floats, integer bps math, `require_auth()` on every state-changing call except the permissionless `finalize_release`, an event per transition.
* **API:** never signs a Stellar transaction, never stores a signing key, never logs secrets or decrypted content. A missing integration is a 503 or a logged skip — never a fabricated success.
* **Web:** no crypto jargon in the product surface, `NEXT_PUBLIC_DEMO_MODE` defaults to `false`, no secret in a `NEXT_PUBLIC_*` var.
* **Everywhere:** email/password auth stays preserved-but-disabled — keep the "do not delete" banners.

## Writing style for docs

* Short, direct sentences. No "seamlessly", "robust", "powerful", "leverage".
* Real numbers over vague claims. If you cite a figure, cite where it's from.
* Every function/endpoint reference states parameters, return type, and who can call it.

## Reporting security issues

Do not open a public issue. Email **<chijiokejoseph2022@gmail.com>** or Telegram **@cjay**. See each repo's `SECURITY.md`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cjay-1.gitbook.io/cjay-docs/contributing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.