# CZBG Workspace

This workspace generates and uploads synthetic cloud billing data to CloudZero
demo organizations. You have skills that guide the full workflow.

## Workflow

```
/demo-plan  →  /demo-generate  →  /demo-upload  →  /demo-status
  (author)       (submit)          (upload)         (monitor)
```

1. **`/demo-plan`** — describe what you need conversationally; it writes the YAML configs
2. **`/demo-generate`** — validates and submits generation jobs (+ variance for base configs)
3. **`/demo-upload`** — discovers datasets, writes upload configs, batch submits to CloudZero
4. **`/demo-status`** — check pipeline progress for a demo or a specific job

## Supported Providers

**Cloud**: AWS, Azure, GCP, Oracle Cloud

**SaaS**: Anthropic, Confluent, Databricks, Datadog, Elastic Cloud, Fastly,
GitHub, MongoDB, New Relic, OpenAI, Snowflake

**Marketplace**: AWS Marketplace

To discover available services for any provider:
```bash
czbg data explore combinations --cloud-provider <name>
```

## Common Questions

**How long does generation take?**
10–60 minutes depending on config size (line item count, number of months).
Large multi-provider demos can take longer. Jobs run on remote ECS workers.

**What's the variance pass?**
After generation, `czbg variance run <dataset_id>` adds realistic hourly/daily
cost jitter. Only needed for base configs — optimize, anomaly, and unit-econ
configs have intentional cost shapes that shouldn't be distorted.

**What's a connection suffix?**
A label on the CloudZero billing connection (e.g., `AcmeCorp`, `AcmeCorp-Anomalies`).
It keeps different uploads separated in CloudZero. Auto-derived from the demo name
and category — you never need to set it manually.

**How do future months work?**
When you upload, past/current months upload immediately. Future months register
with the scheduler and upload automatically when each month becomes current.
This prevents rate-limit issues at CloudZero ingest.

**Where do credentials come from?**
Edit `.env` in this workspace. AWS access uses SSO — run
`aws sso login --profile cz-test-env-1.AdministratorAccess`.

For CloudZero org API keys: get from 1Password (Demo vault) for shared orgs,
or create in CloudZero UI (Settings → API Tokens) for custom orgs.
Add to `.env` as `CZ_ORG_API_KEY_{ORGKEY}=<token>`.

**What permissions does the API key need?**
The key needs two permission groups in CloudZero:
- **Connections** (all 9): read/create/update/delete billing, anycost billing drops, validate
- **Telemetry** (all 4): create/read/delete telemetry streams, manage telemetry records

## Common Gotchas

- **`usage_types: []`** — empty list matches ALL usage types, causing line item
  explosion. Always be explicit.
- **GCP requires `operations: []`** — empty list, not null or specific values.
- **`total_cost` is for the entire date range**, not per month.
  Formula: `monthly_spend × number_of_months`.
- **K8s constraints**: exactly 80 compute resources, 5 clusters, 3 namespaces,
  3 workloads per namespace (45 workload definitions per feature).
- **Line item limit**: <10M per provider across all jobs. Check with
  `czbg analyze config <path>`.

## Config Organization

```
configs/{demo-name}/{provider}/{category}/generate/{feature}/{service}.yaml
configs/{demo-name}/{provider}/{category}/upload/{name}.upload.yaml
```

Categories: `base`, `optimize`, `anomalies`, `unit-econ`

## Quick Command Reference

```bash
# Workspace setup
czbg init                              # initialize workspace
czbg init --refresh-skills             # update skills from package

# Config exploration
czbg data explore combinations         # browse reference data
czbg analyze config <path>             # validate configs

# Jobs
czbg generate run --config-path <path> --description "..."
czbg variance run <dataset_id>         # post-generate jitter (base only)
czbg upload generated --config <path>

# Monitoring
czbg jobs list
czbg jobs describe <job_id>
czbg dataset list
czbg dataset describe <dataset_id>
czbg schedules list

# AWS auth (tokens expire ~8hrs)
aws sso login --profile cz-test-env-1.AdministratorAccess
```

## Workspace Contents

| Path | Purpose |
|------|---------|
| `configs/` | Demo configs organized by demo name |
| `examples/` | Example filter blocks per provider (copy, don't invent) |
| `reference/` | Reference data (billing combinations from real CZ data) |
| `.env` | Credentials (API keys, AWS profile) |
| `.czbg.yaml` | API endpoint and environment settings |
