# SaaS Nightly Fix — Workspace Guidance

You are debugging and fixing failing **Camunda 8 SaaS** nightly Playwright runs
for one minor version (8.7, 8.8, 8.9, or 8.10). The authoritative, always-read
instructions are the **`## SaaS Nightly Fix Agent`** section of this repo's
`AGENTS.md` — read it before doing anything else. This file is supplementary
context about the workspace shape.

## What is in this workspace

- **`c8-cross-component-e2e-tests/`** — the repo you EDIT. SaaS specs live in
  `tests/8.x/` (bare version, no `SM-`/`c8Run-` prefix), page objects in
  `pages/8.x/`, fixtures in `fixtures/8.x.ts`.
- **`camunda-docs/`** — read-only reference for intended product behavior and
  upgrade/behavior-change notes.
- **Possibly one or more product repos** — injected on demand by the dispatcher
  based on which component the failing spec belongs to. You may see
  `camunda-hub/`, `connectors/`, `marketplace-api/`, or `camunda-<version>/`
  (the `camunda/camunda` monorepo). If the repo you need is **not** present, do
  NOT clone it — use `gh search code` / `gh api` instead (below).

## The SaaS environment is gone — fix from artifacts only

The SaaS nightly creates a fresh enterprise org, runs the tests, and **deletes
the org afterwards**. There is no live cluster to re-test against and no
Teleport/kubectl. You diagnose entirely from the nightly artifacts
(`json-report`, screenshots, `trace.zip`) — exactly like c8Run, never like SM's
live-cluster mode. Do not attempt to create an org or run Playwright against a
live endpoint.

## Cross-repo lookups WITHOUT cloning (cost rule)

The product UI repos are large. When the repo you need was not injected, reach
the source with GitHub search instead of a checkout:

```bash
# Find the React component that owns a label / test-id / field
gh search code --repo camunda/camunda-hub "<aria-label or data-testid>" --limit 5 --json path
gh search code --repo camunda/camunda     "<field id or label>"          --limit 5 --json path

# Pin a regression to a commit on a path
gh api 'repos/camunda/camunda/commits?path=identity/client/src/.../X.tsx&per_page=10' \
  --jq '.[] | "\(.commit.author.date|.[0:10]) \(.sha[:7]) \(.commit.message|split("\n")[0])"'
```

Component → repo (also encoded in `scripts/inject-saas-manifest.py`):

| Failing spec | Component | Source repo |
|---|---|---|
| `web-modeler-user-flows`, `play` | Web Modeler | `camunda/camunda-hub` |
| `connectors-user-flows`, `aws-connectors-user-flows` | Connectors / marketplace | `camunda/connectors`, `camunda/marketplace-api` |
| `access-user-role-management`, `idp-user-flows`, `rba-enabled-v2-user-flows` | Identity (8.10+) | `camunda/camunda` (`identity/client/`) |
| `operate-access-flow`, `hto-user-flows`, `optimize-api-tests`, `cluster-variables`, `agentic-ai-user-flows`, `orchestration-cluster-mcp-server/*` | Orchestration | `camunda/camunda` |
| `console-user-flows`, `aws-cluster-user-flows`, `saas-migration-path-user-flows`, `navigation`, `login*`, `smoke-tests` | SaaS Console (private) | none — mirror SM/SaaS page-object patterns in this repo |

> **Identity trap:** for 8.10+, Identity UI lives in `camunda/camunda`
> (`identity/client/src/pages/...`), **not** the legacy `camunda/identity`
> repo. For 8.9 and earlier it is `camunda/identity`. Match the version.

## Deliverable

Edit the test code, lint, open a draft PR labelled `failing-test-fix`, and write
`/tmp/fix-meta.json`. See the `## SaaS Nightly Fix Agent` section of `AGENTS.md`
for the exact PR/commit conventions and the hard constraints (skip allowed ONLY
for a confirmed product bug via the `// Skipped due to bug #<number>: <url>`
annotation per **Product-Bug Escalation** — forbidden otherwise; minimal diff;
the narrow `{"prs":[]}` exit cases).
