---
title: "Follow Project Standards"
url: "https://docs.caracal.run/contributing/style/"
markdown_url: "https://docs.caracal.run/markdown/contributing/style.md"
description: "Repository conventions for code, docs, naming, command ownership, and product boundaries."
page_type: "reference"
concepts: []
requires: []
---

# Follow Project Standards

Canonical URL: https://docs.caracal.run/contributing/style/
Markdown URL: https://docs.caracal.run/markdown/contributing/style.md
Description: Repository conventions for code, docs, naming, command ownership, and product boundaries.
Page type: reference
Concepts: none
Requires: none

---

Caracal style favors small, explicit boundaries and source-aligned documentation.

## Language Style Guides

| Language | Required style | Enforcement |
| --- | --- | --- |
| TypeScript and JavaScript | TypeScript Handbook style plus the repository Prettier profile in `.prettierrc.json`. | `pnpm run style` checks changed TS/JS source files with Prettier. |
| Go | Effective Go with canonical `gofmt` formatting. | `pnpm run style` checks changed Go source files with `gofmt -l`. |
| Python | PEP 8 layout as formatted by Ruff. | `pnpm run style` checks changed Python source files with `ruff format --check`. |

Use `pnpm run style:fix` to format changed files before committing. Pull requests run the same changed-file style gate automatically for primary-language source files.

## Code Conventions

| Convention | Apply it |
| --- | --- |
| Keep changes focused | Avoid unrelated refactors in feature or docs PRs. |
| Prefer explicit validation | Fail closed on auth, policy, config, stream, and key errors. |
| Preserve product boundaries | Do not couple open-source code to enterprise-only code. |
| Respect command ownership | Runtime CLI is lifecycle/setup; Console/Admin/Control own product management. |
| Use existing shared layers | Reuse core config, errors, crypto, logging, engine dispatch, and SDK helpers. |

## Documentation Conventions

| Page type | Pattern |
| --- | --- |
| Landing | Purpose, audience, map, recommended reading path. |
| Workflow | Prerequisites, steps, validation, troubleshooting, related links. |
| Reference | Exact names, defaults, tables, examples, source-of-truth links. |
| Architecture | Diagram, component responsibilities, flow, boundaries, related pages. |

Do not use docs to preserve stale command names, screenshots, package names, or workflows. Update the whole affected page coherently.

## Project Boundaries

- Top-level `caracal` commands are limited to runtime lifecycle, setup, and `caracal run`.
- Product-management workflows for zones, policies, grants, audit, agents, delegation, and Control belong in Console, Admin SDK, or Control API docs.
- Open-source code must not import, reference, or depend on enterprise-only code.
- Security-sensitive findings must follow [Report a Vulnerability](/security/disclosure/), not public issues.

## Naming

Use canonical terms from [Glossary](/reference/glossary/): zone, principal, resource, grant, policy, policy set, mandate, agent session, delegation edge, audit ledger, Console, Control API, STS, Gateway.

## Next Step

Use [Make a Change](/contributing/workflow/) to plan and submit a focused pull request.