Contributing Guidelines

The Short Version

1. Fork the repo and create a topic branch
2. Make your change — code, docs, tests, whatever
3. Run npm run build locally to confirm it compiles
4. Commit with git commit -s (the -s flag adds a DCO sign-off line)
5. Open a pull request with a clear description

Developer Certificate of Origin (DCO)

Every commit to ClawNex must be signed off under the Developer Certificate of Origin. We use DCO instead of a traditional CLA — it is lightweight and does not require paperwork.

How to sign off

git commit -s -m "Add tooltip to Fleet Command Alerts stat"

This appends a Signed-off-by: line to the commit message. The name and email must match your git config user.name and user.email.

Forgot to sign off?

# Amend the last commit
git commit --amend --signoff --no-edit
 
# For older commits in the same branch
git rebase --signoff main

Why DCO

DCO achieves the same legal goal as a CLA — certification that you have the right to contribute — with a single line per commit. Projects that use DCO include the Linux kernel, Docker, Grafana, GitLab, and most CNCF projects.

What to Contribute

• Bug fixes — include a test if you can
• Shield rules — new jailbreak / exfiltration / cognitive tampering patterns (see src/lib/shield/rules.ts)
• Connectors — new agent-framework integrations
• Panels and visualizations — new dashboard tabs, accessibility improvements
• Documentation — clarifications, corrections, tutorials
• Tests — shield test payloads, API test cases
• Performance — profiling, query optimization, bundle size reduction

RBAC Route Requirements

When RBAC is enabled, all new API routes must include requireSession() + requirePermission() guards. Unguarded routes will be rejected in review.

Dependency Policy

• All dependencies must be exact-pinned (no ^, ~, >=)
• No automatic updates (npm update, pip install --upgrade are prohibited)
• LiteLLM is pinned to 1.83.0 — never upgrade without explicit verification