# Agents Documentation for `@rio-cloud/cdk-v2-constructs`

## Purpose

Use this document as the entry point when an agent needs to understand or apply the npm package `@rio-cloud/cdk-v2-constructs` from an installed project. Prefer package-owned documentation in `.d.ts` files and generated type artifacts over memory or guesses.

This package provides RIO-specific AWS CDK v2 constructs and helpers for:

- Watchful and Datadog monitoring for RIO-standard service alerting and observability
- ECS/Fargate services as the paved road for running backend workloads on RIO
- Kafka topics and event sources
- Codified AWS account defaults such as VPC properties and well-known SSM parameters
- Pipeline tagging and delivery monitoring
- Backup policy helpers
- SES observability

## Reference Order

After reaching this document, use these package artifacts as the primary references:

1. Read this file first.
2. Check the installed package's `package.json` exports before using any subpath import or package-local artifact.
3. Read `README.md` for the package-level overview and `docs/AGENTS_RIO_INFRASTRUCTURE_GUIDE.md` for infrastructure-specific project structure, pipeline guardrails, or pipeline-oriented work.

Use `lib/**/*.d.ts` for generated type information and JSDoc-derived annotations. When guidance in this document conflicts with generated package annotations such as `lib/**/*.d.ts`, or `.jsii`, trust the generated package annotations.

## Import And Edit Workflow

Prefer `import * as rio from '@rio-cloud/cdk-v2-constructs';` unless an exported subpath is explicitly available in the installed `package.json`.

Read the relevant declaration comments and examples before writing or changing infrastructure code.

## Usage Guidance

### General

Prefer RIO constructs over raw AWS CDK constructs when the use case matches. These constructs encode RIO infrastructure defaults, Datadog tags, shared secrets, team and account SSM parameters, and monitoring conventions.

Do not set construct attributes explicitly when the value you plan to set is already the construct default. Prefer relying on defaults unless you are intentionally changing behavior and that intent is clear in the code.

Preserve the target repository's existing stack boundaries and scripts when maintaining an existing project.

### Observability

Watchful is RIO's monitoring and alerting abstraction. Prefer `rio.watchfulv2.Watchful` and `rio.datadogv2`. Use legacy `watchful` or `datadog` only when maintaining existing code that already depends on those APIs.

Do not add raw CloudWatch metrics, alarms, or monitoring resources for agent-generated changes. Use RIO monitoring constructs and Datadog-based abstractions for observability.

Treat `rio.SesObservability` logs as PII. Do not forward those logs to third-party services and do not extend retention beyond the construct default.

### RIO Infrastructure Defaults

RIO infrastructure defaults are the baseline VPC, hosted zone, and team/account values provided by the RIO environment. Use `rio.RioLandingZone` helpers for default VPC, hosted zone, team name, team identifier, team email, team alert Slack channel, and account name. Avoid hard-coded VPC IDs, hosted-zone IDs, or parameter names when a helper exists.

### Services

Use `rio.RioFargateService` for ECS/Fargate services when possible.
### Kafka

Use `rio.KafkaTopicV4` for new Kafka topics. Set audience and recovery policy deliberately.

### Backup And Delivery

Use `rio.BackupPolicy`, `rio.ClassifyPipelineType`, and `rio.DeliveryPerformanceMonitoringOverride` for backup and pipeline metadata instead of manually adding equivalent tags. Branch pipelines validate contributions or Renovate updates; vulnerability pipelines run vulnerability-focused checks.