Repository layout and conventions

Use this guide to choose where a change belongs in OpenClaw Enterprise (OCE). The repository contains the OpenClaw Control Plane (OCC), its Go CLI, deployment packaging, and documentation. Read AGENTS.md for agent instructions and Contributing for setup and contribution workflow.

Workspace boundaries

The root pnpm workspace explicitly selects apps/controller and five packages: utils, contracts, occ, iam, and audit. TypeScript project references select the same projects. Adding a directory does not enroll it in the workspace: intentional workspace changes must also update these declarations and the workspace boundary check. The configuration excludes legacy/; do not import archived implementations.

The Go CLI uses the root Go module. The documentation renderer in scripts/docs-site/ has its own package manifest, pnpm workspace, and lockfile; keep its dependency installation separate from the root workspace. API example metadata and export enrichment live in scripts/api-examples.ts and scripts/document-api-examples.ts; scripts/docs-site/ owns the explorer and OpenAPI lint configuration. The controller route schemas remain the source of truth for HTTP behavior.

The console Storybook in scripts/console-storybook/ is also an isolated tool with its own manifest and lockfile. See Console Storybook. Use the standalone interface sketch renderer to describe architecture in TypeScript and generate shareable diagrams.

Within internal/occcli/, cli.go assembles the command tree and resource commands. iam.go owns IAM policy, ServicePrincipal, and service-key commands. agent_runtime.go owns runtime inspection, version selection for runtime reads, and log polling. agent_runtime_output.go owns runtime log text, notices, and Pod diagnostics. output.go owns resource tables, structured output, and shared formatting helpers.

Within internal/occdev/, openshell_assets.go owns local OpenShell chart and manifest selection, verified downloads, and source extraction. openshell.go owns their deployment, workspace resource rendering, and image import.

Source ownership

Start from the existing primitive that owns a capability. Keep platform core behavior dependent on contracts; put implementation-specific behavior in the owning Driver or Backend and wire it through composition. See platform architecture for component interactions, implementation status, and remaining design requirements.

Within packages/contracts/src/, runtime-logs.ts owns runtime inspection and container/Sandbox log types. drivers/index.ts owns the shared base Driver and registry types. Each Driver capability has its own directory with an index.ts, such as drivers/compute/index.ts or drivers/iam/index.ts, containing that Driver's interface, request, context, and result types. The root index.ts retains shared resource definitions and the public package exports.

The container release command starts at scripts/ci/container-release.ts. Its modules under scripts/ci/container-release/ own release admission, receipt validation, OCI verification, native smoke, and registry publication.

Within controller composition, installation-presets.ts owns Preset file loading and bundled-version assembly; installation-config.ts owns Driver composition.

HTTP error details live in apps/controller/src/http/error-details.ts. It translates schema failures into detail paths and expected values. http/errors.ts owns platform-error mapping, response formatting, and removal of request values from verbose validation errors after their details are built.

The repository capability uses RepositoryPolicyDriver and NativeRepositorySender in packages/contracts/src/drivers/repo/index.ts, implemented by drivers/repo/github/policy.ts and drivers/repo/github/driver.ts, respectively. Under apps/controller/src/, its owners are:

• drivers/repo/access/: private common sessions, custody, lifecycle, transport and contracts, including the private client-configuration type.
• drivers/repo/github/access/: GitHub policy, backend and closed Git/gh client bundle.
• drivers/repo/github/public-read/: credential-free public GitHub reader and its Agent skill.
• backends/repository-credentials/control-client.ts: configured private-service connection and complete response validation.
• composition/repository-credentials/: registry and protected-file loading, platform wiring and separate-process assembly.

OCC owns immutable Agent bindings and safe session State; worker helpers connect those records to Compute delivery. Public status omits private cleanup diagnostics. The common engine's RepositoryBackend protocol is separate from these interfaces. The worker Token Service owns GitHub App signing and provider-token custody. The native sender consumes prepared material without an App key. See the Agent repository flow.

The quickstart’s shared operator-session helpers, Agent onboarding, cluster installation fragments and executable examples live under docs/snippets/openshell-quickstart/. Platform setup and cleanup pages remain under docs/guides/deploy/; Add Git and Add Plugin each have one guide for all supported quickstart platforms.

Deployment, tooling, and checks

Repository credential Dockerfiles live under deploy/runtime/repository-credentials/, with the standalone Compose example under deploy/examples/repository-credentials/. The build stages only the selected emitted modules and minimal manifests in .build/repository-credentials/service and .build/repository-credentials/client; the standalone service/client images do not include the controller dependency graph. The full deploy/runtime/Dockerfile uses the repository root as its build context to include the emitted client router in the Agent image. deploy/runtime/openclaw-source.json owns the OpenClaw source commit, archive checksum, and fixed build timestamp used by that runtime recipe and its callers. deploy/runtime/node/ owns the runtime's pinned Node source, termination patch, native build and verification. Its patch inventory is separate from OpenClaw's.

Helm embeds the startup programs from deploy/helm/openclaw-enterprise/files/ in rendered container commands. Edit the TypeScript sources for the API CA programs in deploy/helm/src/. Install the workspace dependencies, then run node deploy/helm/src/generate-api-ca.ts from the repository root with the repository's pinned Node version. Commit the generated chart updates with their sources. The OIDC CA integration suite checks that the chart archive contains the generated programs.

Select checks using the testing guide. Follow AGENTS.md's integration requirements for runtime changes. For documentation-only changes, use formatting, builds, and link checks; do not add or run tests solely for prose.

Code conventions

• Use the existing TypeScript ES module structure and strict settings in tsconfig.base.json. Match neighboring import style.
• Expose package APIs through a curated top-level src/index.ts; use export type for public types. Keep implementation helpers private and avoid ad hoc package subpath exports. Separate entrypoints require a deliberate runtime or platform boundary.
• Place shared utilities in focused modules under packages/utils/src/ when they serve multiple consumers. Keep feature-specific helpers with their owner.
• Use ts-pattern for tagged unions and exhaustive multi-case branches; ordinary two-way conditions can remain if statements or simple ternaries.
• Use the repository's Prettier configuration for authored TypeScript, JavaScript, configuration, and Markdown, and gofmt for Go. With matching dependencies installed, run pnpm format:fix, inspect the diff, then pnpm format:check.
• Keep generated outputs owned by their generator. Update API schemas and routes, then use pnpm openapi:generate and pnpm openapi:check for packages/contracts/openapi/occ-api.openapi.json, docs/reference/api.md, and docs/reference/cheatsheets/api.md.

Documentation placement

Use stable feature names for living references. Follow RFCs and implementation plans for numbering, document ownership, and lifecycle. Prefer one Markdown file per RFC or plan; documents with supporting material use <number>-<topic>/index.md, with companions in the same directory. Keep completed and superseded documents in place. Preserve historical names and content when grouping companions. This first phase does not reorganize specs/.archive/; removed image assets remain accessible through links to a preserved Git commit. Update affected current references, guides, and flows with behavior changes; shipped specifications remain historical records. Keep Manual Notes unchanged. Put detailed contracts in their owning reference rather than expanding architecture pages for every feature.

Put contributor workflows for documentation in docs/contributing/, starting with the writing guide. Existing site-tooling guides and inventories may remain directly under docs/; docs/testing/ owns code verification and test setup. Per-check coverage pages live in docs/testing/ci/ and use the CI check template. The CI index links to those pages; shared configuration and lane procedures have their own pages in that directory. The documentation taxonomy maps page kinds to their templates.

The documentation map has seven menus. Getting Started, Topics, Integrations, Deploy & Operate, and Reference serve product users and operators; Testing & CI serves contributors running and interpreting checks; Contribute serves people changing the platform. A menu opens its sidebar. Register every Markdown page once in docs/docs.json and link it from its owning overview. Deep implementation and testing pages can use the owning tab's hidden list when a contributor index links them; they keep their routes and remain searchable. Cross-link subjects useful to both audiences.

Use relative Markdown links and sentence-case article titles and headings. Keep sidebar labels short and in Title Case; the navigation can assign a separate label. Changing a menu or label does not require moving a file: preserve existing URLs and heading anchors. See the local preview guide for rendering. Review pages above 1,500 visible words and keep them within the 2,500-word hard limit from AGENTS.md.

When directories, package boundaries, or placement conventions change, update this guide and affected navigation in the same change.

The optional deploy/helm/openclaw-observability-demo/ chart owns disposable telemetry backends. Its files/dashboard.json is also the Compose metrics dashboard; Compose provisioning and scraper configurations remain under deploy/metrics/development/.