# Contributing

> License-compatible dependency policy, generate-licenses.sh, PR expectations, and contributor workflow boundaries for backend and frontend changes.

- Repository: vxcontrol/pentagi
- GitHub: https://github.com/vxcontrol/pentagi
- Human docs: https://grok-wiki.com/public/docs/vxcontrol-pentagi-eca0cf4de5f5
- Complete Markdown: https://grok-wiki.com/public/docs/vxcontrol-pentagi-eca0cf4de5f5/llms-full.txt

## Source Files

- `CONTRIBUTING.md`
- `CONTRIBUTORS.md`
- `scripts/generate-licenses.sh`
- `licenses/README.md`
- `LICENSE`
- `.github/PULL_REQUEST_TEMPLATE.md`
- `CLAUDE.md`

---

---
title: "Contributing"
description: "License-compatible dependency policy, generate-licenses.sh, PR expectations, and contributor workflow boundaries for backend and frontend changes."
---

PentAGI is an MIT-licensed monorepo (`backend/` Go API, `frontend/` React + TypeScript UI). Contributions must keep third-party dependencies on MIT-compatible licenses, refresh reports via `scripts/generate-licenses.sh`, and meet the checklist in `.github/PULL_REQUEST_TEMPLATE.md` before merge.

## Project license stack

| Artifact | Role |
|---|---|
| `LICENSE` | MIT License for project source (Copyright 2025 PentAGI Development Team) |
| `NOTICE` | Copyright notice; notes VXControl Cloud SDK AGPL-3.0 with a special exception for this official project |
| `EULA.md` | End-user terms for source, Docker images, and web UI; MIT governs source when terms conflict |
| `licenses/` | Generated third-party dependency license reports (see below) |
| Docker image | Ships `LICENSE`, `NOTICE`, `EULA`, and reports under `/opt/pentagi/licenses/` |

Contact for license questions: **info@pentagi.com** or **info@vxcontrol.com**.

<Note>
VXControl Cloud **service** access (threat intelligence, premium features) is separate from the MIT-licensed SDK code and may require a license key and cloud Terms of Service. Adding or changing that integration is not the same as adding a generic Go/npm dependency.
</Note>

## Dependency license policy

All new dependencies must use licenses compatible with the MIT project license.

### Approved

| License | Notes |
|---|---|
| MIT | Preferred |
| Apache-2.0 | Allowed |
| BSD-2-Clause, BSD-3-Clause | Allowed |
| ISC | Allowed |
| MPL-2.0 | Allowed **if used without modification** |
| 0BSD | Public-domain style; allowed |

### Incompatible

| License | Notes |
|---|---|
| GPL, LGPL, AGPL | Incompatible without a special exception (do not introduce copyleft into the main dependency tree) |
| CC-BY-SA | Not for code; may be acceptable for data assets only |
| Proprietary / commercial | Not allowed as a default dependency |

Do not add a dependency until its SPDX license is in the approved set. If a library is dual-licensed, pin usage to an approved license and document that choice in the PR.

## Generate and review license reports

`scripts/generate-licenses.sh` collects backend and frontend dependency license data into `licenses/`. Generated report files are listed in `licenses/.gitignore`; keep the script and `licenses/README.md` under version control.

### Tools

| Tool | Package surface | Install / use |
|---|---|---|
| `go list -m all` | Go modules | Built into Go; always used by the script |
| `go-licenses` | Go license CSV | `go install github.com/google/go-licenses@latest` |
| `pnpm ls --prod --json` | Frontend prod tree | Requires `pnpm install` in `frontend/` |
| `license-checker` | Frontend license JSON/CSV | Global CLI; optional for local runs |
| `osv-scanner` | Security + license scan | Recommended pre-merge gate |

### Outputs

After a successful local run from the repo root:

```text
licenses/
├── backend-dependencies.txt   # go list -m all
├── backend-licenses.csv       # go-licenses csv ./cmd/pentagi
├── frontend-dependencies.json # pnpm ls --prod --json
├── frontend-licenses.json     # license-checker --production --json
└── frontend-licenses.csv      # license-checker --production --csv
```

Docker multi-stage builds regenerate the same class of reports and copy them into the runtime image:

| Build stage | Path in image |
|---|---|
| Frontend (`license-checker`) | `/opt/pentagi/licenses/frontend/` (`licenses.json`, `licenses.csv`) |
| Backend (`go list`, `go-licenses`) | `/opt/pentagi/licenses/backend/` (`dependencies.txt`, `licenses.csv`) |

### Pre-merge procedure for dependency changes

<Steps>
  <Step title="Tidy and lock dependencies">
    ```bash
    cd backend && go mod tidy
    cd ../frontend && pnpm install
    ```
    Commit `go.mod` / `go.sum` and `pnpm-lock.yaml` with the code change when either changes.
  </Step>
  <Step title="Generate license reports">
    ```bash
    ./scripts/generate-licenses.sh
    ```
    Install `go-licenses` first if backend CSV generation is skipped. Run `pnpm install` in `frontend/` before expecting frontend reports.
  </Step>
  <Step title="Scan for incompatible licenses">
    ```bash
    osv-scanner scan --experimental-licenses="MIT,Apache-2.0,BSD-2-Clause,BSD-3-Clause,ISC,MPL-2.0" backend
    osv-scanner scan --experimental-licenses="MIT,Apache-2.0,BSD-2-Clause,BSD-3-Clause,ISC,MPL-2.0" frontend
    ```
    Resolve any license or vulnerability findings before requesting review.
  </Step>
  <Step title="Document the dependency in the PR">
    Use the PR **Security Considerations** and **Compatibility** sections: name the package, license, and why it is required. Mark breaking or security-sensitive dependency bumps clearly.
  </Step>
</Steps>

## Contributor workflow boundaries

### Monorepo layout

| Path | Stack | Typical change surface |
|---|---|---|
| `backend/` | Go 1.24, Gin REST, gqlgen GraphQL | API, agents, providers, tools, Docker sandbox, DB migrations |
| `frontend/` | React, TypeScript, pnpm, Apollo | UI, settings, GraphQL operations |
| `observability/` | Compose / monitoring configs | Optional Grafana/OTEL stack only |
| `examples/` | Provider YAML, prompts, guides | Copy-paste configs and sample flow inputs |
| `scripts/` | Shell helpers | `generate-licenses.sh`, entrypoint, version helpers |
| `.github/` | CI, issue/PR templates | Workflow and contribution UX |

### Backend change boundaries

Run from `backend/`:

```bash
go mod download
go build -trimpath -o pentagi ./cmd/pentagi
go test ./...
golangci-lint run --timeout=5m
```

Regenerate when schemas or REST annotations change:

| Change | Command |
|---|---|
| `pkg/graph/schema.graphqls` | `go run github.com/99designs/gqlgen --config ./gqlgen/gqlgen.yml` |
| REST swag annotations | `swag init -g ../../pkg/server/router.go -o pkg/server/docs/ --parseDependency --parseInternal --parseDepth 2 -d cmd/pentagi` |
| SQL migrations | Add goose SQL under `backend/migrations/sql/` (applied at startup) |

Utility binaries for local verification (not production entrypoints): `cmd/ctester`, `cmd/ftester`, `cmd/etester`, `cmd/installer`.

PR checklist expects `go fmt` and `go vet` for Go code.

### Frontend change boundaries

Run from `frontend/`:

```bash
pnpm install
pnpm run lint
pnpm run prettier
pnpm run test
pnpm run build
```

| Change | Command / rule |
|---|---|
| `frontend/src/graphql/*.graphql` | `pnpm run graphql:generate` |
| `frontend/src/graphql/` generated types | Do **not** hand-edit; regenerate |
| Dev server | `pnpm run dev` → `http://localhost:8000` |

PR checklist expects `pnpm run lint` for TypeScript/JavaScript.

### Adding a new LLM provider

Cross-cutting changes must land together or the API rejects the type:

1. Implement `provider.Provider` under `backend/pkg/providers/<name>/`.
2. Register type constants and wiring in `pkg/providers/provider/provider.go` and `pkg/providers/providers.go`.
3. Add the type to `Valid()` in `pkg/server/models/providers.go` — missing this returns **422 Unprocessable Entity**.
4. Add env keys in `pkg/config/config.go` (for example `<NAME>_API_KEY`, `<NAME>_SERVER_URL`).
5. Add `PROVIDER_TYPE` via a goose migration in `backend/migrations/sql/`.
6. Add icon + registration under `frontend/src/components/icons/`.
7. Update GraphQL schema / frontend settings if the UI must expose the provider.
8. Run license generation and `osv-scanner` if new modules were introduced.

Keep providers BYOK/BYOC: configuration is env keys, optional server URLs, and YAML agent configs — do not hard-code a single hosted vendor as required.

### Password and token-related changes

When touching registration, password reset, or API token secrets, enforce both backend and frontend validation:

- Minimum **12** characters
- At least one uppercase, one lowercase, one number, one special character
- Reject common weak passwords (for example `password`, `123456`)
- Never rely on frontend-only checks

### Acceptable-use constraint for product changes

`EULA.md` restricts use to authorized penetration testing and research. Features that assume unauthorized access, or that ship attack payloads outside sandboxed tool execution, are out of scope for contribution.

## Pull requests

Incomplete PRs may be closed at maintainers' discretion. Use `.github/PULL_REQUEST_TEMPLATE.md` in full.

### Required narrative

| Section | Expectation |
|---|---|
| **Problem / Solution** | Enough design detail for review without reading the full diff |
| **Closes #** | Link issues when applicable |
| **Type of Change** | Bug, feature, breaking, docs, config, test, or security |
| **Areas Affected** | Core, agents, tools, memory, monitoring, Langfuse, integrations, docs, infra |
| **Testing and Verification** | Repro steps, test config (version, Docker, OS, LLM provider, features), results |
| **Security Considerations** | New deps, permissions, sandbox/network impact |
| **Performance Impact** | Especially for agents, memory, or heavy data paths |
| **Documentation Updates** | README, API docs, config docs, GraphQL schema, other |
| **Deployment Notes** | New env vars, migrations, compose changes |

### Checklist (from template)

**Code quality**

- Coding standards followed
- Docs and tests updated as needed
- New and existing tests pass
- `go fmt` / `go vet` (Go)
- `pnpm run lint` (TS/JS)

**Security**

- Security implications considered
- Security model preserved or improved
- Secrets not committed

**Compatibility**

- Backward compatible, or breaking changes marked and documented
- Dependencies updated correctly (license-compatible)

**Documentation**

- Clear docs and non-obvious comments
- API changes documented

### CI surface

`.github/workflows/ci.yml` runs on every branch push:

| Job step | What it runs |
|---|---|
| Frontend | `pnpm install --frozen-lockfile`, `prettier`, `lint`, `test` |
| Backend | `go mod download`, `golangci-lint`, `go test ./...`, linux/amd64 + arm64 build of `./cmd/pentagi` |
| Docker build/push | Only on `main` or version tags `vX.Y.Z`; multi-arch image `vxcontrol/pentagi` |

Many lint/test steps currently use `continue-on-error: true`. Treat local green checks as the merge bar even when CI soft-fails.

## Issues

Use the structured templates under `.github/ISSUE_TEMPLATE/`:

| Template | Use for |
|---|---|
| Bug report | Repro steps, component multi-select, system config, enabled features (Langfuse/Grafana/custom LLM) |
| Enhancement | Problem statement, proposed solution, optional technical approach and security notes |

Default assignee for both templates is the project lead (`asdek`).

## Contributor recognition

`CONTRIBUTORS.md` lists core team and external contributors with linked PRs. After a history rewrite on March 29, 2026 (licensing cleanup), individual commit history may not appear in GitHub's UI; contribution credit is preserved in that document. Point new significant work at a PR and, when maintainers update the list, at `CONTRIBUTORS.md`.

## Local stack for end-to-end verification

```bash
cp .env.example .env   # set DB + at least one LLM provider key
docker compose up -d
# optional overlays:
# docker compose -f docker-compose.yml -f docker-compose-observability.yml up -d
# docker compose -f docker-compose.yml -f docker-compose-langfuse.yml up -d
# docker compose -f docker-compose.yml -f docker-compose-graphiti.yml up -d
docker build -t local/pentagi:latest .
```

UI: `https://localhost:8443`. Prefer changing default admin credentials before any shared or long-lived environment.

## Troubleshooting

| Symptom | Likely cause | Action |
|---|---|---|
| `go-licenses` step skipped | Tool not on `PATH` | `go install github.com/google/go-licenses@latest` |
| Frontend license files empty | No `frontend/node_modules` | `pnpm install` in `frontend/`, re-run script |
| `osv-scanner` flags GPL/AGPL | Incompatible transitive dep | Replace package or pin an approved license path |
| Provider create returns 422 | Type not in `Valid()` whitelist | Update `pkg/server/models/providers.go` + migration |
| GraphQL types out of date | Schema or `.graphql` ops changed without codegen | Run gqlgen and/or `pnpm run graphql:generate` |
| PR closed for missing info | Template incomplete | Fill Problem/Solution, tests, security, areas affected |

## Related pages

<CardGroup>
  <Card title="Development and testing" href="/development-and-testing">
    Backend go build/test, frontend pnpm scripts, codegen, and helper binaries for contributors.
  </Card>
  <Card title="Configure LLM providers" href="/configure-llm-providers">
    Env keys and UI profiles when a contribution adds or changes a provider.
  </Card>
  <Card title="Environment variables" href="/environment-variables">
    Config keys and defaults that deployment notes in a PR must document.
  </Card>
  <Card title="Installation" href="/installation">
    Compose stack and volumes for local end-to-end verification of a change.
  </Card>
</CardGroup>