@bluedynamics/cdk8s-plone 0.1.4 → 0.1.6

package/.jsii

@@ -108,7 +108,7 @@
   },
   "name": "@bluedynamics/cdk8s-plone",
   "readme": {
-    "markdown": "# CDK8S Plone\n\nA CDK8S library for deploying Plone CMS to Kubernetes.\n\nThis library provides constructs to bootstrap a Plone deployment on a Kubernetes cluster using the [CDK8S](https://cdk8s.io) framework.\n\n## Features\n\n- **Backend**: Plone backend (API with `plone.volto` or Classic-UI)\n- **Frontend**: Plone Volto (modern React-based user interface)\n- **Varnish Caching**: Optional HTTP caching layer using [kube-httpcache](https://github.com/mittwald/kube-httpcache) with cluster-wide cache invalidation\n- **High Availability**: Configurable replicas with PodDisruptionBudgets\n- **Multi-language Support**: Published to npm (TypeScript/JavaScript) and PyPI (Python)\n\n\n## Installation\n\n### TypeScript/JavaScript\n\nCreate a new CDK8S project (or use an existing one):\n\n```bash\ncdk8s init typescript-app\n```\n\nInstall the library:\n\n```bash\nnpm install @bluedynamics/cdk8s-plone\n```\n\nPackage: [@bluedynamics/cdk8s-plone](https://www.npmjs.com/package/@bluedynamics/cdk8s-plone)\n\n### Python\n\nCreate a new CDK8S project:\n\n```bash\ncdk8s init python-app\n```\n\nInstall the library:\n\n```bash\npip install cdk8s-plone\n```\n\nPackage: [cdk8s-plone](https://pypi.org/project/cdk8s-plone/)\n\n\n## Quick Start\n\n### Basic Plone Deployment\n\n```typescript\nimport { App, Chart } from 'cdk8s';\nimport { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';\n\nconst app = new App();\nconst chart = new Chart(app, 'PloneDeployment');\n\nnew Plone(chart, 'my-plone', {\n  variant: PloneVariant.VOLTO,\n  backend: {\n    image: 'plone/plone-backend:6.0.10',\n    replicas: 3,\n  },\n  frontend: {\n    image: 'plone/plone-frontend:16.0.0',\n    replicas: 2,\n  },\n});\n\napp.synth();\n```\n\n### With Varnish HTTP Cache\n\n```typescript\nimport { PloneHttpcache } from '@bluedynamics/cdk8s-plone';\n\nconst plone = new Plone(chart, 'my-plone', {\n  variant: PloneVariant.VOLTO,\n  backend: { image: 'plone/plone-backend:6.0.10' },\n  frontend: { image: 'plone/plone-frontend:16.0.0' },\n});\n\nnew PloneHttpcache(chart, 'cache', {\n  plone: plone,\n  existingSecret: 'varnish-secret',\n  replicas: 2,\n});\n```\n\n### Generate Kubernetes Manifests\n\n```bash\ncdk8s synth\n```\n\nThe manifests are stored in the `dist/` directory.\n\nFor a complete example, see the [example project](https://github.com/bluedynamics/cdk8s-plone-example).\n\n## Prerequisites\n\n- **kubectl** - Command-line tool for deploying Kubernetes manifests. [Install kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)\n- **Helm** (optional) - Only needed if generating Helm charts. [Install Helm](https://helm.sh/docs/intro/install/)\n- **Node.js** - For TypeScript/JavaScript development\n- **Python 3.8+** - For Python development\n\n\n## API Documentation\n\nFor complete API documentation, see [API.md](./API.md).\n\n### Key Constructs\n\n#### `Plone`\n\nMain construct for deploying Plone CMS. Supports two variants:\n- **VOLTO**: Modern React frontend with REST API backend (default)\n- **CLASSICUI**: Traditional server-side rendered Plone\n\nProperties:\n- `backendServiceName` - Name of the backend Kubernetes service\n- `frontendServiceName` - Name of the frontend service (VOLTO only)\n- `variant` - Deployment variant (VOLTO or CLASSICUI)\n- `siteId` - Plone site ID in ZODB (default: 'Plone')\n\n#### `PloneHttpcache`\n\nVarnish HTTP caching layer using the [kube-httpcache](https://github.com/mittwald/kube-httpcache) Helm chart.\n\nProperties:\n- `httpcacheServiceName` - Name of the Varnish service\n\n### Configuration Options\n\n#### `PloneOptions`\n\n- `version` - Version of your project\n- `siteId` - Plone site ID (default: 'Plone')\n- `variant` - PloneVariant.VOLTO or PloneVariant.CLASSICUI (default: VOLTO)\n- `backend` - Backend configuration (PloneBaseOptions)\n- `frontend` - Frontend configuration (PloneBaseOptions, required for VOLTO)\n- `imagePullSecrets` - Image pull secrets for private registries\n\n#### `PloneBaseOptions`\n\nConfiguration for backend or frontend:\n\n**Container:**\n- `image` - Container image (e.g., 'plone/plone-backend:6.0.10')\n- `imagePullPolicy` - Pull policy (default: 'IfNotPresent')\n- `replicas` - Number of replicas (default: 2)\n- `environment` - Environment variables (cdk8s-plus-30.Env)\n\n**Resources:**\n- `requestCpu` / `limitCpu` - CPU requests/limits\n- `requestMemory` / `limitMemory` - Memory requests/limits\n\n**High Availability:**\n- `minAvailable` - Min pods during updates (for PodDisruptionBudget)\n- `maxUnavailable` - Max unavailable pods during updates\n\n**Health Probes:**\n- `readinessEnabled` - Enable readiness probe (default: true)\n- `readinessInitialDelaySeconds` / `readinessTimeoutSeconds` / `readinessPeriodSeconds`\n- `readinessSuccessThreshold` / `readinessFailureThreshold`\n- `livenessEnabled` - Enable liveness probe (default: false, recommended true for frontend)\n- `livenessInitialDelaySeconds` / `livenessTimeoutSeconds` / `livenessPeriodSeconds`\n- `livenessSuccessThreshold` / `livenessFailureThreshold`\n\n**Annotations:**\n- `annotations` - Deployment metadata annotations\n- `podAnnotations` - Pod template annotations (e.g., for Prometheus)\n- `serviceAnnotations` - Service annotations (e.g., for external-dns)\n\n#### `PloneHttpcacheOptions`\n\n- `plone` - Plone construct to attach cache to (required)\n- `varnishVcl` - VCL configuration as string\n- `varnishVclFile` - Path to VCL configuration file\n- `existingSecret` - Kubernetes secret for Varnish admin credentials\n- `replicas` - Number of Varnish replicas (default: 2)\n- `requestCpu` / `limitCpu` - CPU resources\n- `requestMemory` / `limitMemory` - Memory resources\n- `servicemonitor` - Enable Prometheus ServiceMonitor (default: false)\n- `exporterEnabled` - Enable Prometheus exporter sidecar (default: true)\n- `chartVersion` - kube-httpcache Helm chart version (default: latest)\n\n\n## Development\n\nThis project uses [Projen](https://projen.io/) to manage project configuration. **Do not edit generated files directly.**\n\n### Setup\n\nClone the repository and install dependencies:\n\n```bash\nnvm use lts/*\ncorepack enable\nnpx projen\n```\n\n### Common Commands\n\n```bash\n# Run tests\nnpx projen test\n\n# Run tests in watch mode\nnpx projen test:watch\n\n# Build (compile TypeScript + generate JSII bindings)\nnpx projen build\n\n# Lint\nnpx projen eslint\n\n# Generate API documentation\nnpx projen docgen\n\n# Package for distribution\nnpx projen package-all\n```\n\n### Making Changes\n\n1. Edit `.projenrc.ts` for project configuration changes\n2. Run `npx projen` to regenerate project files\n3. Make code changes in `src/`\n4. Run tests and update snapshots if needed: `npx projen test -- -u`\n\n## References\n\n- [CDK8S Documentation](https://cdk8s.io/)\n- [Kubernetes Probes Documentation](https://kubernetes.io/docs/concepts/configuration/liveness-readiness-startup-probes/)\n- [kube-httpcache Helm Chart](https://github.com/mittwald/kube-httpcache)\n- [Example Project](https://github.com/bluedynamics/cdk8s-plone-example)\n\n## License\n\nSee [LICENSE](./LICENSE) file."
+    "markdown": "# CDK8S Plone\n\n> TypeScript and Python library for deploying Plone CMS to Kubernetes using CDK8S\n\n[![npm version](https://badge.fury.io/js/%40bluedynamics%2Fcdk8s-plone.svg)](https://www.npmjs.com/package/@bluedynamics/cdk8s-plone)\n[![PyPI version](https://badge.fury.io/py/cdk8s-plone.svg)](https://pypi.org/project/cdk8s-plone/)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n\n## Overview\n\ncdk8s-plone provides CDK8S constructs for deploying [Plone CMS](https://plone.org/) on Kubernetes. Define your infrastructure using TypeScript or Python and generate Kubernetes manifests automatically.\n\n**Key Features:**\n- 🚀 Supports Volto (modern React frontend) and Classic UI\n- 📦 High availability with configurable replicas\n- ⚡ Optional Varnish HTTP caching layer\n- 🔧 Fine-grained resource and probe configuration\n- 🌍 Multi-language support (TypeScript/JavaScript and Python)\n- ✅ Type-safe infrastructure as code\n\n## Quick Start\n\n### Installation\n\n**TypeScript/JavaScript:**\n```bash\nnpm install @bluedynamics/cdk8s-plone\n```\n\n**Python:**\n```bash\npip install cdk8s-plone\n```\n\n### Basic Example\n\n```typescript\nimport { App, Chart } from 'cdk8s';\nimport { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';\n\nconst app = new App();\nconst chart = new Chart(app, 'PloneDeployment');\n\nnew Plone(chart, 'my-plone', {\n  variant: PloneVariant.VOLTO,\n  backend: {\n    image: 'plone/plone-backend:6.1.3',\n    replicas: 3,\n  },\n  frontend: {\n    image: 'plone/plone-frontend:16.0.0',\n    replicas: 2,\n  },\n});\n\napp.synth();\n```\n\nGenerate Kubernetes manifests:\n```bash\ncdk8s synth\nkubectl apply -f dist/\n```\n\n## Documentation\n\n**📚 Full documentation:** https://bluedynamics.github.io/cdk8s-plone/\n\n- [Quick Start Tutorial](https://bluedynamics.github.io/cdk8s-plone/tutorials/01-quick-start.html)\n- [Configuration Reference](https://bluedynamics.github.io/cdk8s-plone/reference/configuration-options.html)\n- [Architecture Overview](https://bluedynamics.github.io/cdk8s-plone/explanation/architecture.html)\n- [Complete API Documentation](./API.md)\n\n## Examples\n\nSee the [cdk8s-plone-example](https://github.com/bluedynamics/cdk8s-plone-example) repository for complete working examples.\n\n## Requirements\n\n- **kubectl** - [Install kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)\n- **Node.js 16+** (for TypeScript/JavaScript) - [Install Node.js](https://nodejs.org/)\n- **Python 3.8+** (for Python) - [Install Python](https://www.python.org/)\n- **Kubernetes cluster** (local or cloud)\n\nFor detailed setup instructions, see [Setup Prerequisites](https://bluedynamics.github.io/cdk8s-plone/how-to/setup-prerequisites.html).\n\n## Development\n\nThis project uses [Projen](https://projen.io/) for project management.\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n\n# Update project configuration\n# Edit .projenrc.ts, then run:\nnpx projen\n```\n\nFor detailed development instructions, see [CONTRIBUTING.md](./CONTRIBUTING.md) (if available).\n\n## Resources\n\n- [CDK8S Documentation](https://cdk8s.io/)\n- [Plone CMS](https://plone.org/)\n- [kube-httpcache](https://github.com/mittwald/kube-httpcache) (for HTTP caching)\n- [Example Project](https://github.com/bluedynamics/cdk8s-plone-example)\n\n## License\n\n[Apache 2.0](LICENSE)\n\n## Maintainers\n\nMaintained by [Blue Dynamics Alliance](https://github.com/bluedynamics)\n\n**Author:** Jens W. Klein (jk@kleinundpartner.at)\n"
   },
   "repository": {
     "type": "git",
@@ -771,7 +771,7 @@
         },
         "locationInModule": {
           "filename": "src/httpcache.ts",
-          "line": 113
+          "line": 120
         },
         "parameters": [
           {
@@ -797,7 +797,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/httpcache.ts",
-        "line": 106
+        "line": 113
       },
       "name": "PloneHttpcache",
       "properties": [
@@ -810,7 +810,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/httpcache.ts",
-            "line": 111
+            "line": 118
           },
           "name": "httpcacheServiceName",
           "type": {
@@ -852,6 +852,25 @@
             "fqn": "@bluedynamics/cdk8s-plone.Plone"
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "undefined (chartVersion = with each chart release there is an image release too )",
+            "remarks": "If not specified, the latest version from the repository will be used.",
+            "stability": "stable",
+            "summary": "Version of the kube-httpcache Container Image to use."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/httpcache.ts",
+            "line": 88
+          },
+          "name": "appVersion",
+          "optional": true,
+          "type": {
+            "primitive": "string"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -955,7 +974,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/httpcache.ts",
-            "line": 87
+            "line": 94
           },
           "name": "replicas",
           "optional": true,
@@ -1229,6 +1248,6 @@
       "symbolId": "src/plone:PloneVariant"
     }
   },
-  "version": "0.1.4",
-  "fingerprint": "hTVlbqlLeJ3QLMbm2blqTcPywb8qi1KzLxS48UE1NdM="
+  "version": "0.1.6",
+  "fingerprint": "depZZYpzfH8bEtxQEeVuqwlkPEPyCD3pZVw9TOCbtE8="
 }

package/API.md

@@ -809,6 +809,7 @@ const ploneHttpcacheOptions: PloneHttpcacheOptions = { ... }
 | **Name** | **Type** | **Description** |
 | --- | --- | --- |
 | <code><a href="#@bluedynamics/cdk8s-plone.PloneHttpcacheOptions.property.plone">plone</a></code> | <code><a href="#@bluedynamics/cdk8s-plone.Plone">Plone</a></code> | The Plone construct to attach the HTTP cache to. |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneHttpcacheOptions.property.appVersion">appVersion</a></code> | <code>string</code> | Version of the kube-httpcache Container Image to use. |
 | <code><a href="#@bluedynamics/cdk8s-plone.PloneHttpcacheOptions.property.chartVersion">chartVersion</a></code> | <code>string</code> | Version of the kube-httpcache Helm chart to use. |
 | <code><a href="#@bluedynamics/cdk8s-plone.PloneHttpcacheOptions.property.existingSecret">existingSecret</a></code> | <code>string</code> | Name of an existing Kubernetes secret containing Varnish admin credentials. |
 | <code><a href="#@bluedynamics/cdk8s-plone.PloneHttpcacheOptions.property.exporterEnabled">exporterEnabled</a></code> | <code>boolean</code> | Enable the Prometheus exporter for Varnish metrics. |
@@ -837,6 +838,21 @@ The cache will automatically connect to the backend and frontend services.
 
 ---
 
+##### `appVersion`<sup>Optional</sup> <a name="appVersion" id="@bluedynamics/cdk8s-plone.PloneHttpcacheOptions.property.appVersion"></a>
+
+```typescript
+public readonly appVersion: string;
+```
+
+- *Type:* string
+- *Default:* undefined (chartVersion = with each chart release there is an image release too )
+
+Version of the kube-httpcache Container Image to use.
+
+If not specified, the latest version from the repository will be used.
+
+---
+
 ##### `chartVersion`<sup>Optional</sup> <a name="chartVersion" id="@bluedynamics/cdk8s-plone.PloneHttpcacheOptions.property.chartVersion"></a>
 
 ```typescript

package/CLAUDE.md

@@ -0,0 +1,352 @@
+# Claude Code Project Guide
+
+This document provides context and guidelines for Claude Code when working on this project.
+
+## Project Overview
+
+**cdk8s-plone** is a TypeScript/Python library for deploying Plone CMS to Kubernetes using CDK8S constructs. It provides type-safe infrastructure as code with support for Volto (React frontend) and Classic UI deployments.
+
+## Git Workflow
+
+**IMPORTANT: Never merge directly to `main`**
+
+This project uses a Pull Request workflow:
+
+1. **Create a feature branch** from `main`:
+   ```bash
+   git checkout -b feature/description
+   # or
+   git checkout -b docs/description
+   # or
+   git checkout -b fix/description
+   ```
+
+2. **Make commits** on the feature branch with descriptive messages
+
+3. **Create a Pull Request** to merge into `main`:
+   - Use GitHub UI or `gh` CLI
+   - PRs are required for code review
+   - Never push directly to `main`
+   - Never merge locally to `main`
+
+4. **PR will be reviewed and merged** by maintainers
+
+### Branch Naming Conventions
+
+- `feat/` or `feature/` - New features
+- `fix/` - Bug fixes
+- `docs/` - Documentation changes
+- `chore/` - Maintenance tasks
+- `refactor/` - Code refactoring
+- `test/` - Test additions or changes
+
+## Working with Worktrees
+
+**Recommended for parallel development and multi-instance work**
+
+Git worktrees allow you to work on multiple branches simultaneously without switching contexts. This is especially useful when:
+- Multiple Claude Code instances are working on different features
+- You need to switch between features frequently
+- You want to keep branches completely isolated
+
+### Setting Up Worktrees
+
+**Create a worktree for each feature branch:**
+
+```bash
+# From the main repository
+git worktree add ../cdk8s-plone-feature-name feature/feature-name
+
+# For existing branches
+git worktree add ../cdk8s-plone-docs docs/diataxis-sphinx-skeleton
+
+# For new branches
+git worktree add -b feat/new-feature ../cdk8s-plone-new-feature
+```
+
+**Directory structure with worktrees:**
+```
+~/ws/cdev/
+├── cdk8s-plone/              # Main repository (usually on main branch)
+├── cdk8s-plone-docs/         # Worktree for documentation work
+├── cdk8s-plone-frontend/     # Worktree for frontend features
+└── cdk8s-plone-monitoring/   # Worktree for monitoring features
+```
+
+### Working with Worktrees
+
+**List all worktrees:**
+```bash
+git worktree list
+```
+
+**Remove a worktree when done:**
+```bash
+# Delete the worktree directory first
+rm -rf ../cdk8s-plone-feature-name
+
+# Then prune the worktree reference
+git worktree prune
+```
+
+**Switch between worktrees:**
+```bash
+# Simply cd to the worktree directory
+cd ../cdk8s-plone-docs
+
+# Each worktree is an independent working directory
+# with its own checked out branch
+```
+
+### Worktree Best Practices
+
+1. **One feature per worktree**: Keep each worktree focused on a single feature or task
+2. **Clean up after merge**: Remove worktrees once their branches are merged
+3. **Use descriptive directory names**: Name worktrees after their branch or feature
+4. **Regular git fetch**: Run `git fetch` in any worktree to update all branch references
+5. **Avoid nested worktrees**: Don't create worktrees inside other worktrees
+
+### Example Workflow with Worktrees
+
+```bash
+# Setup: Create worktree for documentation work
+cd ~/ws/cdev/cdk8s-plone
+git worktree add -b docs/add-tutorial ../cdk8s-plone-docs
+
+# Work: Make changes in the worktree
+cd ../cdk8s-plone-docs
+# ... make documentation changes ...
+git add . && git commit -m "docs: add new tutorial"
+git push -u origin docs/add-tutorial
+
+# Create PR using gh CLI
+gh pr create --title "Add new tutorial" --body "..."
+
+# Cleanup: After PR is merged
+cd ~/ws/cdev/cdk8s-plone
+git fetch
+git pull  # Update main branch
+rm -rf ../cdk8s-plone-docs
+git worktree prune
+```
+
+### Benefits of Worktrees
+
+- ✅ **No branch switching**: Keep different features in separate directories
+- ✅ **Parallel work**: Multiple Claude instances can work independently
+- ✅ **Clean state**: Each worktree maintains its own working directory state
+- ✅ **Fast context switching**: Just `cd` between directories
+- ✅ **No uncommitted changes conflicts**: Each worktree is isolated
+
+## Project Structure
+
+```
+.
+├── src/               # TypeScript source code
+│   ├── plone.ts      # Main Plone construct
+│   ├── service.ts    # Service utilities
+│   └── ...
+├── test/             # Jest tests
+├── documentation/    # Sphinx documentation (Diataxis framework)
+│   ├── sources/      # Documentation source files
+│   ├── Makefile      # Build automation (mxmake)
+│   └── README.md     # Documentation contributor guide
+├── .projenrc.ts      # Projen project configuration
+├── API.md            # Auto-generated API documentation
+└── README.md         # Main project README
+```
+
+## Build System
+
+This project uses **Projen** for project management.
+
+**⚠️ DO NOT edit generated files directly**
+
+Generated files include:
+- `package.json`
+- `tsconfig.json`
+- `.gitignore`
+- GitHub Actions workflows (except custom ones)
+- And more...
+
+### Making Changes
+
+1. **Edit `.projenrc.ts`** for project configuration changes
+2. **Run `npx projen`** to regenerate files
+3. **Make code changes** in `src/`
+4. **Run tests**: `npx projen test`
+5. **Update snapshots if needed**: `npx projen test -- -u`
+
+### Common Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npx projen test
+
+# Run tests in watch mode
+npx projen test:watch
+
+# Build (compile + generate bindings)
+npx projen build
+
+# Lint
+npx projen eslint
+
+# Generate API docs
+npx projen docgen
+
+# Package for distribution
+npx projen package-all
+
+# Update project files after .projenrc.ts changes
+npx projen
+```
+
+## Documentation
+
+Documentation uses **Sphinx** with the **Diataxis framework**:
+
+- **Tutorials**: Learning-oriented, step-by-step guides
+- **How-To Guides**: Goal-oriented, problem-solving recipes
+- **Reference**: Information-oriented, technical specifications
+- **Explanation**: Understanding-oriented, concepts and design
+
+### Building Documentation
+
+```bash
+cd documentation
+
+# Build HTML
+make docs
+
+# Live-reload development server
+make docs-live
+
+# Clean and rebuild
+make clean && make docs
+```
+
+### Documentation Deployment
+
+- Documentation auto-deploys to GitHub Pages on push to `main`
+- Workflow: `.github/workflows/documentation.yml`
+- Published at: `https://bluedynamics.github.io/cdk8s-plone/`
+
+## Testing
+
+- **Framework**: Jest
+- **Test location**: `test/` directory
+- **Snapshots**: Used for testing generated Kubernetes manifests
+- **Update snapshots**: `npx projen test -- -u`
+
+## Multi-Language Support
+
+The library is published in multiple languages via JSII:
+
+- **TypeScript/JavaScript**: `@bluedynamics/cdk8s-plone` on npm
+- **Python**: `cdk8s-plone` on PyPI
+
+JSII configuration is in `package.json` under the `jsii` field.
+
+## Code Style
+
+- **Linter**: ESLint with TypeScript support
+- **Style**: Configured via `.projenrc.ts`
+- **Run linter**: `npx projen eslint`
+
+## Commit Messages
+
+Follow conventional commit format:
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `chore`: Maintenance tasks
+- `refactor`: Code refactoring
+- `test`: Test additions or changes
+- `ci`: CI/CD changes
+
+**Example:**
+```
+feat(plone): add support for custom environment variables
+
+Allow passing custom environment variables to backend and frontend
+containers using the cdk8s-plus-30 Env API.
+
+Closes #123
+```
+
+All commits from Claude Code include:
+```
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+## CI/CD
+
+GitHub Actions workflows:
+
+- **build.yml**: Build, test, and package
+- **release.yml**: Create releases and publish to npm/PyPI
+- **upgrade-main.yml**: Dependency upgrades
+- **pull-request-lint.yml**: PR validation
+- **documentation.yml**: Build and deploy docs to GitHub Pages
+
+## Dependencies
+
+### Runtime Dependencies
+
+- `cdk8s` - CDK8S framework
+- `cdk8s-plus-30` - CDK8S plus constructs
+- `constructs` - Construct base classes
+
+### Development Dependencies
+
+- `projen` - Project management
+- `jsii` - Multi-language support
+- `jest` - Testing
+- `typescript` - Language
+- `eslint` - Linting
+
+## Publishing
+
+**Do not manually publish packages**
+
+Publishing is automated via GitHub Actions on release:
+1. Create and push a git tag (via `npx projen release`)
+2. GitHub Actions builds and publishes to npm and PyPI
+3. Release notes are auto-generated
+
+## Important Notes
+
+- **Never merge to main**: Always create PRs
+- **Don't edit generated files**: Use `.projenrc.ts` and run `npx projen`
+- **Update snapshots after changes**: Run `npx projen test -- -u`
+- **Follow Diataxis**: When adding docs, use the correct category
+- **Documentation builds required**: Run `make docs` to verify doc changes
+
+## Resources
+
+- [CDK8S Documentation](https://cdk8s.io/)
+- [Projen Documentation](https://projen.io/)
+- [Diataxis Framework](https://diataxis.fr/)
+- [JSII Documentation](https://aws.github.io/jsii/)
+- [Example Project](https://github.com/bluedynamics/cdk8s-plone-example)
+
+## Maintainer Contact
+
+**Author:** Jens W. Klein (jk@kleinundpartner.at)
+**Organization:** [Blue Dynamics Alliance](https://github.com/bluedynamics)