Contributing

Zeq is an open-core project. We welcome contributions to every part of the open stack. The non-open parts are labeled clearly in the repo, and PRs that touch them will be declined — it's not personal, those are the bits that keep the lights on.

What's open

• Protocol registry (app/artifacts/api-server/src/lib/protocols.ts)
• All reference applications (app/artifacts/api-server/public/apps/*)
• SDK source — TypeScript (app/packages/sdk/), MCP (app/packages/zeqsdk-mcp/), Python (app/sdk/python/)
• Operator registry (app/packages/sdk/src/operators.ts)
• Documentation (sdk-docs/source/)
• Integration tests (app/artifacts/api-server/tests/)

What's closed

• API gateway runtime (app/artifacts/api-server/src/app.ts, src/routes/auth.ts, etc.) — binary-only release.
• Key issuance & signing service.
• Compute backend.
• Internal ops tooling (app/deploy/, app/scripts/internal/).
• Hosted HulyaPulse clock.

The repo is structured so the open pieces can be built and run without any closed piece. The closed pieces are replaceable locally — you can self-host the full stack, just with your own keys and your own clock.

Ways to contribute

Add a protocol

Edit app/artifacts/api-server/src/lib/protocols.ts and append a new entry:

{
  id: "zeq-your-protocol",
  category: "Applied Physics",
  description: "One-line description",
  formula: "Your_formula_here = ...",
  operators: ["KO42", "QM9", "NM23"],
  params: {
    m_kg:   { type: "number", required: true, description: "mass, kg" },
    v_mps:  { type: "number", required: true, description: "velocity, m/s" },
  },
  example: {
    params: { m_kg: 1, v_mps: 100 },
    expected: { /* ... */ },
  },
}

Run cd sdk-docs/source && npm run build — the generator will emit a docs page automatically.

Port the SDK to a new language

Highest-impact contribution. See Build → SDKs → Python for what a port looks like. Target interface parity with @zeq-os/sdk:

ZeqClient              → thin wrapper over the hosted API
pulse()                → local pulse read
unixToZeqond / zeqondToUnix  → deterministic math, no network
getOperators / DOMAINS → operator registry (ported from sdk/src/operators.ts)
ZeqMail / ZeqMesh / ZeqDaemon clients  → vertical API wrappers

Languages we'd especially like to see: Go, Rust, Java, C#, Ruby, PHP.

Fix an app / build a new one

Apps live in app/artifacts/api-server/public/apps/<app-name>/. Each is a static bundle (HTML + inline JS/CSS). Guidelines:

• One app, one directory.
• index.html at the root.
• No frameworks with runtime builds — ship pre-built assets only.
• Call the SDK via the CDN build (for non-Node apps) or a bundled copy.
• Mark it as open-source: Apache-2.0 header in each source file.

Documentation

This docs site is Docusaurus. Content is in sdk-docs/source/docs/. PRs welcome.

PR workflow

1. Fork github.com/hulyasmath/zeq-framework.
2. Branch off main.
3. Write the change + tests.
4. Run pnpm run build && pnpm test at the repo root.
5. Open the PR. We review on the HulyaPulse — 1.287 Hz is real, but review cadence is human.

Governance

The framework has a technical custodian (Zeq H — founder) who has final say on merges to main. That's pragmatic: the framework's math has to be consistent, and one person has to own that consistency. Expect:

• Fast iteration on apps and SDK code.
• Slower, more careful review on anything touching operators or the protocol schema.
• No PRs accepted that claim ≤0.1% error without a working KO42 proof.

Code of conduct

Be kind. The framework is a serious mathematical project; criticism is welcome, cruelty is not.