Skip to main content
Version: Deploy Next

CLAUDE.md — Digital.ai Deploy Documentation

Behavioral guidelines for Claude Code working in this repository. Read this before taking any action.

Project context​

  • Product: Digital.ai Deploy — an application release automation tool that models and automates the deployment of applications to target environments (on-premises, cloud, and Kubernetes).
  • Site: Docusaurus, source code hosted on GitHub, GitHub Actions for CD, and distribution via Amazon CloudFront/S3.
  • Production URL: https://docs.digital.ai/deploy/
  • Docs root: docs/ with subdirectories: how-to/, concept/, release-notes/, cloud-native/, docker/, glossary/, faqs/, stitch/, xl-platform/.
  • Branch convention: Feature branches named S-XXXXXX, PRs merged to main.
  • Audience: DevOps engineers, release managers, and deployment engineers using Digital.ai Deploy.

Docusaurus site layout​

All Docusaurus configuration lives under website/, not the repo root.

  • website/docusaurus.config.js — site config
  • website/sidebars.json — navigation structure for the current (next/unreleased) version; see the Sidebars section below
  • website/constants.json — variables for the current version (see below)
  • website/versions.json — list of published versions (read this file for the current list; do not rely on any version list in this CLAUDE.md)

The docs/ directory at the repo root is the next (unreleased) version. It is not listed in versions.json.

Versioned docs​

Each published version has a frozen snapshot:

AssetPath pattern
Docs contentwebsite/versioned_docs/version-X/
Sidebarwebsite/versioned_sidebars/version-X-sidebars.json
Constantswebsite/versioned_constants/version-X-constants.json

Do not edit versioned docs directly unless explicitly asked. Changes to past versions must be intentional and scoped. When adding a new page to the current docs, add an entry to website/sidebars.json — versioned sidebars are not updated automatically.

Backporting changes to versioned docs​

Backporting applies a change from the current (docs/) version to one or more published versions.

Always ask which version(s) to backport to before making any changes.

The versioned docs mirror the directory structure of docs/ exactly. The path mapping is:

docs/subdir/page.md  →  website/versioned_docs/version-X/subdir/page.md

What to update per backport:

Change typeFiles to update
Content edit on existing pagewebsite/versioned_docs/version-X/subdir/page.md only
New page addedContent file above + website/versioned_sidebars/version-X-sidebars.json
Constants value changedwebsite/versioned_constants/version-X-constants.json (rarely needed; VAR:: tokens resolve per-version automatically)

Backporting rules:

  • Backport bug fixes, factual corrections, and critical updates. Do not backport new feature docs to old versions unless explicitly instructed.
  • Apply the same surgical-edits rule: change only what was changed in the current version. Do not clean up surrounding content in versioned files.
  • After editing a versioned doc, verify the id in front matter still matches the filename — versioned copies must preserve the original ID.

website/sidebars.json is a large file (~3100 lines). Do not read it whole. Use jq or grep to locate specific sections before editing.

The file has seven top-level sidebar keys, each representing a separate guide:

KeyGuide labelPurpose
docsUser GuideEnd-user tasks: applications, environments, deployments, deployment packages, satellites, security
pluginSidebarPlugins and IntegrationsPlugin docs grouped by category (Cloud/Container, SCM, CI/CD, middleware, provisioning, etc.)
installUpgradeSidebarInstallation GuideInstall, upgrade, authentication, security, administration for JVM, Kubernetes, and Docker
adminSidebarAdministration GuideUsers, roles, system settings, licensing, plugin management, maintenance, troubleshooting
asCodeSidebarDevOps as CodeXL CLI, YAML/blueprints, DevOps as Code workflows
cloudNativeSidebarCloud NativeCloud-native scenario tutorials
apiDocsSidebarAPI DocsREST/CLI/DSL and other developer API references

Node types in the JSON:

// Document leaf node
{ "type": "doc", "id": "how-to/page-name", "label": "Nav Label" }

// Category with a doc as its landing page
{ "type": "category", "label": "Category Label", "collapsed": true,
  "link": { "type": "doc", "id": "concept/landing-page" },
  "items": [ ... ] }

// Category with an auto-generated index page
{ "type": "category", "label": "Category Label", "collapsed": true,
  "link": { "type": "generated-index", "title": "...", "description": "..." },
  "items": [ ... ] }

// External link
{ "type": "link", "label": "Label", "href": "https://..." }

Doc IDs are relative paths under docs/, without the .md extension. Examples: how-to/page-name, concept/page-name, xl-platform/operator/page-name.

Adding a new page:

  1. Identify which guide (sidebar key) and which category the page belongs to — ask if unclear.
  2. Use jq to find the target location: jq '.docs[] | select(.label == "User Guide")' website/sidebars.json
  3. Insert the doc entry at the correct position within items. Match surrounding indentation.
  4. The label field is the nav text and does not need to match the page's front matter title.

Editing rules:

  • Never flatten or re-sort items in a category without being explicitly asked.
  • Never change collapsed values unless asked.
  • When moving a page between categories, remove it from the old location in the same edit.
  • No duplicate doc IDs. Each id must appear exactly once across the entire file. Duplicates cause cyclic reference errors at build time. Before adding a doc entry, verify the ID is not already present: grep -n '"id": "how-to/page-name"' website/sidebars.json.

Constants​

website/constants.json stores version-specific variables: product name, version numbers, supported OS/database/browser/JDK versions, and external URLs. Read this file to find the current published version — do not rely on any version string in this CLAUDE.md.

Use VAR::<key> tokens instead of hardcoding values from constants.json. Docusaurus replaces these at build time with the value from the version-appropriate constants file. Use dot notation for nested keys.

Examples:

  • 26.3 → the short version number (e.g. 26.3)
  • 26.3.x → the full version string (e.g. 26.3.x)
  • 25 → the required JDK version
  • 26.04 LTS / 24.04 LTS → supported Ubuntu versions
  • 18.3 / 17.9 → supported PostgreSQL versions
  • Digital.ai Deploy → Digital.ai Deploy

When you write or edit any doc that mentions a version number, OS, browser, database, or JDK version, replace the literal value with the appropriate VAR:: token. Use literals only for specific historical versions where the exact number is the point (for example, "fixed after upgrading from 25.3.x"). Each past version resolves tokens from its own frozen constants file in website/versioned_constants/.

Writing new pages​

File naming and IDs​

  • Filenames are lowercase kebab-case: my-new-page.md.
  • The id field in front matter must exactly match the filename without the .md extension.
  • The sidebar entry "id" must also match. A mismatch causes a build error.

Directory placement​

DirectoryUse for
how-to/Task-oriented step-by-step guides. The user performs an action. Title usually starts with a verb: "Configure...", "Create...", "Set up..."
concept/Explanatory, overview, or reference content. The user learns something. Titles are noun phrases: "Deployment Life Cycle", "Core Concepts"
release-notes/Release notes only
cloud-native/Cloud-native scenario tutorials
docker/Docker installation and configuration
faqs/Frequently asked questions
stitch/Stitch-related content
xl-platform/Platform/Kubernetes operator content, often shared across Deploy and Release
glossary/Glossary entries

When in doubt between how-to/ and concept/: if a reader follows steps to accomplish something, it's a how-to. If a reader is building understanding, it's a concept.

Front matter​

Every page requires this front matter block at the top:

---
id: my-page-filename          # required; must match filename without .md
title: Page Title             # required; displayed as the page H1
product:                      # required; one or more of: deploy, release, xl-platform
- deploy
description: One sentence summarizing what the page covers. Used by search engines and site search.  # required
tags:                         # optional but recommended; used for search filtering
- keyword
- another-keyword
---

sidebar_label is rarely used — the label in sidebars.json controls the nav text. Do not add it unless there is a specific reason.

Screenshots and images​

All static image assets live in website/static/deploy-images/. This is a single shared folder — both current (docs/) and versioned (website/versioned_docs/) pages reference images here. There are no per-version image folders.

Never replace an existing PNG file when a UI changes. Old versioned docs still reference the original file, so overwriting it would break or misrepresent those pages. Instead, add a new file with a distinct name (typically prefixed with the version number, for example 26.3-kubernetes-create-resource.png) and update only the current doc to point to it.

When reviewing or writing image references:

  • The path in Markdown is relative to website/static/, so a file at website/static/deploy-images/foo.png is referenced as /deploy-images/foo.png.
  • Subdirectories under deploy-images/ (for example, kubernetes/, concurrent_deployments/) are used to group screenshots by plugin or feature area. Place new screenshots in the appropriate subdirectory, or in the root deploy-images/ folder if no subdirectory fits.
  • There is no requirement for all images in a single doc to be in the same subdirectory. The path in the Markdown reference is what matters.

TW style rules​

Follow these without exception.

  1. No purple prose. No narrative scene-setting, elaborate metaphors, or evocative descriptions. State facts plainly.

  2. No marketing language. Describe what something does, not how great it is. Never write copy that sells the product or the role.

  3. No em-dashes. Replace with: "such as" (when introducing examples), a comma, or a new sentence.

  4. Examples run inside the sentence (Microsoft Style Guide). Introduce examples with "such as" or "like", set off by commas. Do not wrap examples in parentheses with "for example".

    ✗ "a database other than PostgreSQL (for example, Oracle or SQL Server)" ✓ "a database other than PostgreSQL, such as Oracle or SQL Server"

  5. No semicolons, and no colons that join clauses (Microsoft Style Guide). When two statements share a sentence, connect them with a comma and a conjunction, or split them into two sentences. A colon is allowed only to introduce a list, a table, a code block, or a bolded term in a list item.

    ✗ "The conceptual settings are the same as for Keycloak; only the navigation differs by vendor." ✓ "The conceptual settings are the same as for Keycloak. Only the navigation differs by vendor." ✗ "AI Assistant is read-only and permission-scoped: it can only return data you are authorized to view." ✓ "AI Assistant is read-only and permission-scoped, and it can only return data you are authorized to view."

  6. Direct preambles. One short sentence stating what a section covers. No narrative wind-up.

  7. Opening paragraphs: State who the guide is for and what it covers. Do not set a scene.

  8. Lead-in text: Never place an H3 immediately after an H2 without at least one sentence of introductory text.

  9. Links: Use relative links (e.g. ../how-to/some-page) for cross-references within the same doc version. Use the pathname:/// protocol (e.g. pathname:///docs/how-to/some-page) for cross-version links — Docusaurus will not rewrite or version-prefix these, so the path resolves to the same URL regardless of which version the reader is on. Use absolute URLs only for genuinely external resources.

  10. Admonitions: Use Docusaurus admonition blocks sparingly. Each type has a specific purpose:

TypeUse for
:::noteSupplementary context or non-obvious information the reader needs
:::tipBest practices, shortcuts, or optional improvements
:::cautionPotential issues or important considerations that could cause problems
:::warningRisk of data loss, breaking changes, or irreversible actions
:::infoNeutral informational callouts; prefer :::note unless :::info is already established in the surrounding context

Titles are optional: :::warning Custom Title. Do not stack multiple admonitions consecutively — fold the content into prose instead.

What NOT to write:

  • "Digital.ai Deploy is your deployment command center."
  • "without the headaches of manual, error-prone releases"
  • "becomes the single source of truth that keeps every environment in perfect sync"
  • "the model that ensures nothing ever slips through the cracks"

Product terminology​

Use these terms consistently. Inconsistent capitalization or naming is a common error.

TermUsage
Digital.ai DeployFull product name. Use on first mention in a page or in titles.
DeployShortened product name after first mention. Always capitalized when referring to the product.
a deploymentLowercase. An instance of deploying an application to an environment (not the product).
applicationA versioned unit that groups deployables. Lowercase unless starting a sentence.
deployment packageA specific version of an application, containing deployables. Lowercase.
deployableAn item in a deployment package that maps to a deployed item. Lowercase.
deployed applicationThe result of deploying a package to an environment. Lowercase.
environmentA grouping of infrastructure or containers that an application is deployed to. Lowercase.
Configuration Item (CI)The core object-model unit. Capitalize "Configuration Item"; "CI" on subsequent mention.
satelliteA remote agent used for distributed deployments. Lowercase.
workerA node in a master-worker (high-availability) setup. Lowercase.
pluginAn integration extension. Lowercase.
dictionaryA set of key-value entries for environment-specific values. Lowercase.

Disambiguation — "Deploy" vs "a deployment":

"Use Deploy to run a deployment to the test environment." ✓ "Use Deploy to run a Deployment to the test environment." ✗

When the product name and an object name appear in the same sentence, rewrite to avoid ambiguity if possible:

"In Digital.ai Deploy, each run that pushes an application to an environment is called a deployment." ✓

Behavioral guidelines (adapted from Karpathy)​

1. Think before writing​

State your assumptions before drafting. If uncertain about scope, audience, or product behavior, ask first.

  • If a request has multiple valid interpretations, present them. Do not pick silently.
  • If a simpler approach exists, say so.
  • If something is unclear, stop and name what is confusing.

2. Simplicity first​

Minimum content that answers the question. Nothing speculative.

  • No sections or steps beyond what was asked.
  • No "helpful" context that wasn't requested.
  • If a paragraph can be a sentence, make it a sentence.
  • If you write 200 words and it could be 80, rewrite it.

3. Surgical edits​

Touch only what you were asked to change.

  • Do not improve adjacent paragraphs, headings, or formatting you were not asked about.
  • Match the existing doc style, even if you would do it differently.
  • If you notice an unrelated problem (broken link, wrong term), mention it — do not fix it silently.
  • When your edit orphans a cross-reference or link, clean up only that orphan.

4. Goal-driven execution​

Before starting a multi-step doc task, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]

For a doc change, success means: a user can complete the task after reading the section, with no ambiguity.

These guidelines are working if: diffs are tight and scoped, no rewrites of untouched content, and style questions are raised before drafting rather than after.

Last updated on