Draft AGENTS.md file

Signed-off-by: Andrei Kvapil <kvapss@gmail.com>

AGENTS.md

@@ -0,0 +1,449 @@
+# AGENTS.md
+
+This file provides structured guidance for AI coding assistants and agents
+working with the **Cozystack** project.
+
+## Project Overview
+
+Cozystack is an open-source Kubernetes-based platform and framework for building cloud infrastructure. It provides:
+
+- **Managed Services**: Databases, VMs, Kubernetes clusters, object storage, and more
+- **Multi-tenancy**: Full isolation and self-service for tenants
+- **GitOps-driven**: FluxCD-based continuous delivery
+- **Modular Architecture**: Extensible with custom packages and services
+- **Developer Experience**: Simplified local development with cozypkg tool
+
+The platform exposes infrastructure services via the Kubernetes API with ready-made configs, built-in monitoring, and alerts.
+
+## Code Layout
+
+```
+.
+├── packages/               # Main directory for cozystack packages
+│   ├── core/              # Core platform logic charts (installer, platform)
+│   ├── system/            # System charts (CSI, CNI, operators, etc.)
+│   ├── apps/              # User-facing charts shown in dashboard catalog
+│   └── extra/             # Tenant-specific applications
+├── dashboards/            # Grafana dashboards for monitoring
+├── hack/                  # Helper scripts for local development
+│   └── e2e-apps/         # End-to-end application tests
+├── scripts/               # Scripts used by cozystack container
+│   └── migrations/       # Version migration scripts
+├── docs/                  # Documentation
+│   └── changelogs/       # Release changelogs
+├── cmd/                   # Go command entry points
+│   ├── cozystack-api/
+│   ├── cozystack-controller/
+│   └── cozystack-assets-server/
+├── internal/              # Internal Go packages
+│   ├── controller/       # Controller implementations
+│   └── lineagecontrollerwebhook/
+├── pkg/                   # Public Go packages
+│   ├── apis/
+│   ├── apiserver/
+│   └── registry/
+└── api/                   # Kubernetes API definitions (CRDs)
+    └── v1alpha1/
+```
+
+### Package Structure
+
+Every package is a Helm chart following the umbrella chart pattern:
+
+```
+packages/<category>/<package-name>/
+├── Chart.yaml                           # Chart definition and parameter docs
+├── Makefile                             # Development workflow targets
+├── charts/                              # Vendored upstream charts
+├── images/                              # Dockerfiles and image build context
+├── patches/                             # Optional upstream chart patches
+├── templates/                           # Additional manifests
+├── templates/dashboard-resourcemap.yaml # Dashboard resource mapping
+├── values.yaml                          # Override values for upstream
+└── values.schema.json                   # JSON schema for validation and UI
+```
+
+## Conventions
+
+### Helm Charts
+- Follow **umbrella chart** pattern for system components
+- Include upstream charts in `charts/` directory (vendored, not referenced)
+- Override configuration in root `values.yaml`
+- Use `values.schema.json` for input validation and dashboard UI rendering
+
+### Go Code
+- Follow standard **Go conventions** and idioms
+- Use **controller-runtime** patterns for Kubernetes controllers
+- Namespaces follow pattern: `github.com/cozystack/cozystack/<path>`
+- Add proper error handling and structured logging
+- Use `declare(strict_types=1)` equivalent (Go's type safety)
+
+### Git Commits
+- Use format: `[component] Description`
+- Reference PR numbers when available
+- Keep commits atomic and focused
+- Follow conventional commit format for changelogs
+
+### Documentation
+- Keep README files current
+- Document breaking changes clearly
+- Update relevant docs when making changes
+- Use clear, concise language with code examples
+
+## Development Workflow
+
+### Standard Make Targets
+
+Every package includes a `Makefile` with these targets:
+
+```bash
+make update  # Update Helm chart and versions from upstream
+make image   # Build Docker images used in the package
+make show    # Show rendered Helm templates
+make diff    # Diff Helm release against live cluster objects
+make apply   # Apply Helm release to Kubernetes cluster
+```
+
+### Using cozypkg
+
+The `cozypkg` tool wraps Helm and Flux for local development:
+
+```bash
+cozypkg show       # Render manifests (helm template)
+cozypkg diff       # Show live vs desired manifests
+cozypkg apply      # Upgrade/install HelmRelease and sync
+cozypkg suspend    # Suspend Flux reconciliation
+cozypkg resume     # Resume Flux reconciliation
+cozypkg get        # Get HelmRelease resources
+cozypkg list       # List all HelmReleases
+cozypkg delete     # Uninstall release
+cozypkg reconcile  # Trigger Flux reconciliation
+```
+
+### Example: Updating a Component
+
+```bash
+cd packages/system/cilium    # Navigate to package
+make update                  # Pull latest upstream
+make image                   # Build images
+git diff .                   # Review manifest changes
+make diff                    # Compare with cluster
+make apply                   # Deploy to cluster
+kubectl get pod -n cozy-cilium  # Verify deployment
+git commit -m "[cilium] Update to vX.Y.Z"
+```
+
+## Adding New Packages
+
+### For System Components (operators, CNI, CSI, etc.)
+
+1. Create directory: `packages/system/<component-name>/`
+2. Create `Chart.yaml` with component metadata
+3. Add upstream chart to `charts/` directory
+4. Create `values.yaml` with overrides
+5. Generate `values.schema.json` using `readme-generator`
+6. Add `Makefile` using `scripts/package.mk`
+7. Create `images/` directory if custom images needed
+8. Add to bundle configuration in `packages/core/platform/`
+9. Write tests in `hack/e2e-apps/`
+10. Update documentation
+
+### For User Applications (apps catalog)
+
+1. Create directory: `packages/apps/<app-name>/`
+2. Define minimal user-facing parameters in `values.schema.json`
+3. Use Cozystack API for high-level resources
+4. Add `templates/dashboard-resourcemap.yaml` for UI display
+5. Keep business logic in system operators, not in app charts
+6. Test deployment through dashboard
+7. Document usage in README
+
+### For Extra/Tenant Applications
+
+1. Create in `packages/extra/<app-name>/`
+2. Follow same structure as apps
+3. Not shown in catalog
+4. Installable only as tenant component
+5. One application type per tenant namespace
+
+## Tests and CI
+
+### Local Testing
+- **Unit tests**: Go tests in `*_test.go` files
+- **Integration tests**: BATS scripts in `hack/e2e-apps/`
+- **E2E tests**: Full platform tests via `hack/e2e.sh`
+
+### Running E2E Tests
+
+```bash
+cd packages/core/testing
+make apply    # Create testing sandbox in cluster
+make test     # Run end-to-end tests
+make delete   # Remove testing sandbox
+
+# Or locally with QEMU VMs:
+./hack/e2e.sh
+```
+
+### CI Pipeline
+- Automated tests run on every PR
+- Image builds for changed packages
+- Manifest diff generation
+- E2E tests on full platform
+- Release packaging and publishing
+
+### Testing Environment Commands
+
+```bash
+make exec     # Interactive shell in sandbox
+make login    # Download kubeconfig (requires mirrord)
+make proxy    # Enable SOCKS5 proxy (requires mirrord + gost)
+```
+
+## Things Agents Should Not Do
+
+### Never Edit These
+- Do not modify files in `/vendor/` (Go dependencies)
+- Do not edit generated files: `zz_generated.*.go`
+- Do not change `go.mod`/`go.sum` manually (use `go get`)
+- Do not edit upstream charts in `packages/*/charts/` directly (use patches)
+- Do not modify image digests in `values.yaml` (generated by build)
+
+### Version Control
+- Do not commit built artifacts from `packages/*/build/`
+- Do not commit generated dashboards
+- Do not commit test artifacts or temporary files
+
+### Git Operations
+- Do not force push to main/master
+- Do not skip hooks (--no-verify, --no-gpg-sign)
+- Do not update git config
+- Do not perform destructive operations without explicit request
+
+### Changelogs
+- Do not manually edit `docs/changelogs/*.md` outside of changelog workflow
+- Follow changelog agent rules in `.cursor/changelog-agent.md`
+- Use structured format from templates
+
+### Core Components
+- Do not modify `packages/core/installer/installer.sh` without understanding migration impact
+- Do not change `packages/core/platform/` logic without testing full bootstrap
+- Do not alter FluxCD configurations without considering reconciliation loops
+
+## Special Workflows
+
+### Changelog Generation
+
+When working with changelogs (see `.cursor/changelog-agent.md` for details):
+
+1. **Activation**: Automatic when user mentions "changelog" or works in `docs/changelogs/`
+2. **Commands**:
+   - "Create changelog for vX.Y.Z" → Generate from git history
+   - "Review changelog vX.Y.Z" → Analyze quality
+   - "Update changelog with PR #XXXX" → Add entry
+3. **Process**:
+   - Extract version and range
+   - Run git log between versions
+   - Categorize by BMAD framework
+   - Generate structured output
+   - Validate against checklist
+4. **Templates**: Use `patch-template.md` or `template.md`
+
+### Building Cozystack Container
+
+```bash
+cd packages/core/installer
+make image-cozystack    # Build cozystack image
+make apply              # Apply to cluster
+kubectl get pod -n cozy-system
+kubectl get hr -A       # Check HelmRelease objects
+```
+
+### Building with Custom Registry
+
+```bash
+export REGISTRY=my-registry.example.com/cozystack
+cd packages/system/component-name
+make image
+make apply
+```
+
+## Buildx Configuration
+
+Install and configure Docker buildx for multi-arch builds:
+
+```bash
+# Kubernetes driver (build in cluster)
+docker buildx create \
+  --bootstrap \
+  --name=buildkit \
+  --driver=kubernetes \
+  --driver-opt=namespace=tenant-kvaps,replicas=2 \
+  --platform=linux/amd64 \
+  --platform=linux/arm64 \
+  --use
+
+# Or use local Docker (omit --driver* options)
+docker buildx create --bootstrap --name=local --use
+```
+
+## References
+
+- [Cozystack Documentation](https://cozystack.io/docs/)
+- [Developer Guide](https://cozystack.io/docs/development/)
+- [GitHub Repository](https://github.com/cozystack/cozystack)
+- [Helm Documentation](https://helm.sh/docs/)
+- [FluxCD Documentation](https://fluxcd.io/flux/)
+- [cozypkg Tool](https://github.com/cozystack/cozypkg)
+- [Kubernetes Operator Patterns](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
+- [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime)
+
+## Community
+
+- [Telegram](https://t.me/cozystack)
+- [Slack](https://kubernetes.slack.com/archives/C06L3CPRVN1)
+- [Community Calendar](https://calendar.google.com/calendar?cid=ZTQzZDIxZTVjOWI0NWE5NWYyOGM1ZDY0OWMyY2IxZTFmNDMzZTJlNjUzYjU2ZGJiZGE3NGNhMzA2ZjBkMGY2OEBncm91cC5jYWxlbmRhci5nb29nbGUuY29t)
+
+---
+
+## Machine-Readable Summary
+
+```yaml
+project: Cozystack
+type: kubernetes-platform
+description: Open-source platform for building cloud infrastructure
+architecture: kubernetes-based, gitops-driven, multi-tenant
+
+layout:
+  packages/:
+    core/: platform bootstrap and configuration
+    system/: cluster-wide components (CSI, CNI, operators)
+    apps/: user-facing applications (catalog)
+    extra/: tenant-specific applications
+  dashboards/: grafana monitoring dashboards
+  hack/: development scripts and e2e tests
+  scripts/: runtime scripts and migrations
+  cmd/: go command entry points
+  internal/: internal go packages
+  pkg/: public go packages
+  api/: kubernetes api definitions (CRDs)
+  docs/: documentation and changelogs
+
+package_structure:
+  Chart.yaml: helm chart definition
+  Makefile: development workflow targets
+  charts/: vendored upstream charts
+  images/: docker image sources
+  patches/: upstream chart patches
+  templates/: additional manifests
+  values.yaml: configuration overrides
+  values.schema.json: validation schema and UI hints
+
+workflow:
+  development_tool: cozypkg
+  commands:
+    - update: pull upstream charts
+    - image: build docker images
+    - show: render manifests
+    - diff: compare with cluster
+    - apply: deploy to cluster
+  gitops_engine: FluxCD
+  package_manager: Helm
+
+conventions:
+  helm:
+    pattern: umbrella chart
+    upstream: vendored in charts/
+    overrides: root values.yaml
+  go:
+    style: standard go conventions
+    framework: controller-runtime
+    namespace: github.com/cozystack/cozystack
+  git:
+    commit_format: "[component] Description"
+    reference_prs: true
+    atomic_commits: true
+
+testing:
+  unit: go test
+  integration: bats scripts (hack/e2e-apps/)
+  e2e: hack/e2e.sh
+  sandbox:
+    location: packages/core/testing
+    commands: [apply, test, delete, exec, login, proxy]
+
+ci:
+  triggers: every PR
+  checks:
+    - automated tests
+    - image builds
+    - manifest diffs
+    - e2e tests
+    - packaging
+
+special_agents:
+  changelog:
+    activation:
+      - files in docs/changelogs/
+      - user mentions "changelog"
+      - changelog-related requests
+    config_file: .cursor/changelog-agent.md
+    templates:
+      - docs/changelogs/patch-template.md
+      - docs/changelogs/template.md
+    framework: BMAD categorization
+
+do_not_edit:
+  - vendor/
+  - zz_generated.*.go
+  - packages/*/charts/* (use patches)
+  - go.mod manually
+  - go.sum manually
+  - image digests in values.yaml
+  - built artifacts
+
+tools:
+  required:
+    - kubectl
+    - helm
+    - docker buildx
+    - make
+    - go
+  recommended:
+    - cozypkg
+    - mirrord
+    - gost
+    - readme-generator
+
+core_components:
+  bootstrap:
+    - packages/core/installer (installer.sh, assets server)
+    - packages/core/platform (flux config, reconciliation)
+  api:
+    - cmd/cozystack-api (api server)
+    - cmd/cozystack-controller (main controller)
+    - api/v1alpha1 (CRD definitions)
+  delivery:
+    - FluxCD Helm Controller
+    - HelmRelease custom resources
+
+bundle_system:
+  definition: packages/core/platform/
+  components_from: packages/system/
+  user_applications: packages/apps/ + packages/extra/
+  tenant_isolation: namespace-based
+  one_app_type_per_tenant: true
+
+image_management:
+  location: packages/*/images/
+  build: make image
+  injection: automatic to values.yaml
+  format: path + digest
+  registry: configurable via REGISTRY env var
+
+multi_arch:
+  tool: docker buildx
+  platforms: [linux/amd64, linux/arm64]
+  driver_options: [kubernetes, docker]
+```
+