Contributing

Ódinn Forge is early-stage infrastructure. Contributions should preserve cross-platform behavior, explicit security boundaries, durable state transitions, and a small understandable core.

Requirements

• Node.js 24 or newer
• Corepack
• Git

corepack enable
corepack prepare pnpm@10.14.0 --activate
pnpm install --frozen-lockfile
pnpm check

The repository defaults to one workspace/build worker, one dependency lifecycle worker, and a bounded Node.js heap to avoid exhausting a development machine.

Design constraints

• Keep platform-specific behavior behind platform interfaces.
• Do not acknowledge durable work before persistence succeeds.
• Do not grant a capability merely because a model can see a tool.
• Keep provider secrets and generated credentials out of source control.
• Treat generated or imported packages as untrusted, reviewable, and reversible.
• Avoid hidden fallback behavior that changes security or billing semantics.
• Add failure-path tests for state transitions and recovery.

Pull requests

Use a focused branch and a Conventional Commit pull-request title, such as:

feat(gateway): add replayable event cursor
fix(store): recover expired queue leases
docs(console): clarify activity filters

Explain:

• the behavior being changed;
• security implications;
• cross-platform impact;
• exact verification performed.

Local checks

At minimum, run the checks relevant to the change. The full candidate path includes formatting, lint, type checking, unit and integration tests, inference protocol smoke, dependency audit, build, package creation, checksums, verification, install smoke, soak, and storage recovery.

Do not describe a local synthetic provider as live cloud-provider validation.

Read the maintained CONTRIBUTING.md before opening a pull request.