Skip to content

Contributing

This section is the contributor reference. It assumes you read code and want to understand the architecture, extend it, or send a pull request. If you only want to run the bot, start at Get started instead.

Start here

AGENTS.md at the repo root (the CLAUDE.md symlink points at it) is the north-star design and invariant list — read it first. Then the deep-dives:

  • Tech stack & components — what the repo is built from and what actually runs on a server.
  • Worker pipeline — the tick lifecycle, from market event to committed order.
  • Reliability — crash-only guarantees and the self-healing mechanisms the worker upholds.
  • Account isolation — the typed, scope-first data model that prevents cross-account leaks.

Extending it

The two extension points are strategies and notifiers, both plug-ins behind a contract. Adding either is a new package (or provider) plus a registry entry — never a change to apps/api or apps/worker.

Reference

  • Environment variables — process-level .env config.
  • Notifiers — provider contract and config.
  • Strategy pages — the canonical per-strategy references (behaviour, full config, scenarios, internals): Trailing Trade · Momentum · Rebalance.
  • API — the running app serves interactive OpenAPI docs (Swagger UI) at /docs, with the spec at /openapi.json. Profile config is edited in the app; its schema lives in packages/contracts (Zod).

Contributing

Read the engineering charter in AGENTS.md at the repo root before your first pull request — it lists the invariants, the required commands, and the quality gates CI enforces.

  • Coding rules — narrower conventions, including the documentation-accuracy rules.
  • CI secrets — the image-tag scheme and the secrets table live in docs/ci-secrets.md in the repository. It is deliberately not published to this site: it maps which secrets exist in which provider and which job reads them, which is an infrastructure map rather than contributor documentation.
  • Dependency updates — automated by Renovate (renovate.json), the only dependency bot; there is no Dependabot config. Routine updates arrive weekly on chore/renovate-* branches as two grouped pull requests: one for every non-major bump, one for every major. Grouping spans managers because the Bun and Playwright versions are each duplicated across package.json, both CI providers and the Dockerfile, and only move consistently when one PR moves every managed copy. Two paths sit outside it: lock-file maintenance opens its own PR against the same two-PR budget, and a security update ignores the concurrency limits and the schedule so a fix is never queued behind a routine bump. A dependency that must not advance is an allowedVersions rule with the reason in its description — never enabled: false, which drops it off the dashboard, and never a silent hand-pin.

Run the worker integration lane locally

The apps/worker integration suites are excluded from bun run test: they need real Postgres and Redis, which CI supplies as service containers. Locally, one command provisions them:

bun run test:worker-integration

It requires a running Docker daemon and prints a one-line reason instead of failing when there isn't one. The lane then audits its own vitest report and prints every suite that stood down together with the reason, so a run that covered less than it looks like cannot pass unnoticed.

Run the docs site locally

The documentation you're reading is built with MkDocs. Requires uv (Python 3.14.7 or newer):

uv sync --group docs
uv run mkdocs serve   # http://127.0.0.1:8000

The bun run docs:* scripts are thin wrappers around those commands.