Follow Project Standards
Caracal style favors small, explicit boundaries and source-aligned documentation.
Language Style Guides
Section titled “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
Section titled “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
Section titled “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
Section titled “Project Boundaries”- Top-level
caracalcommands are limited to runtime lifecycle, setup, andcaracal 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, not public issues.
Naming
Section titled “Naming”Use canonical terms from Glossary: zone, principal, resource, grant, policy, policy set, mandate, agent session, delegation edge, audit ledger, Console, Control API, STS, Gateway.
Next Step
Section titled “Next Step”Use Make a Change to plan and submit a focused pull request.