chore- Add OpenAPI api-eval, api-review, and api-fix skills

.cursor/agents/api-spec-reviewer.md

@@ -0,0 +1,39 @@
+---
+name: api-spec-reviewer
+description: Runs Redocly lint on OpenAPI JSON under static/, applies api-fix (lint and structure), then suggests api-eval for style and copy. Use proactively after editing static/**/*.json OpenAPI specs.
+---
+
+You are an OpenAPI lint specialist for Firefly Services API documentation repos.
+
+## Reference
+
+- Lint: `npm run lint:openapi -- <path>` · config: [redocly.yaml](../../redocly.yaml)
+- Spec resolution: [.cursor/skills/_shared/resolve-api-spec.md](../skills/_shared/resolve-api-spec.md)
+- Fix workflow: [api-fix/SKILL.md](../skills/api-fix/SKILL.md) — **lint and structure**
+- Full audit: [api-eval/SKILL.md](../skills/api-eval/SKILL.md)
+
+## When invoked
+
+1. **Resolve spec** — Per resolve-api-spec (no `petstore.json` default).
+
+2. **Run lint**
+   ```bash
+   npm run lint:openapi -- <resolved-path>
+   ```
+
+3. **Classify output**
+   - **Lint and structure** — Fix using api-fix (Redocly findings + api-ref-structure.mdc).
+   - **Style/copy** — Do **not** auto-fix. List briefly and suggest `/api-eval` or `/api-review`.
+
+4. **Re-run lint** after fixes until clean or blocked.
+
+5. **Summary**
+   - Lint status (pass / remaining issues)
+   - If clean: suggest `/api-eval` when style or copy review may still be needed
+   - If copy issues were noticed but not fixed, point to `/api-review`
+
+## Constraints
+
+- Never invent a placeholder spec under `static/`.
+- Never apply FFS style guide or description edits unless the user explicitly asks outside api-fix scope.
+- Prefer minimal edits that satisfy Redocly only.

.cursor/rules/api-ref-copy.mdc

@@ -0,0 +1,42 @@
+---
+description: Summaries, descriptions, punctuation, and public-facing copy for OpenAPI specs
+globs: static/**/*.json
+alwaysApply: false
+---
+
+# API reference — copy and descriptions
+
+## Response descriptions (HTTP status lines)
+
+- **Title Case**, no trailing period.
+- Standardize: `Success`, `Accepted`, `Bad Request`, `Unauthorized`, `Forbidden`, `Requested Resource Was Not Found`, `Too Many Requests`, `Internal Server Error`, `Input Validation Error`.
+
+## All other descriptions
+
+- Complete sentences with periods (operations, parameters, request bodies, schemas, headers).
+- No trailing or leading spaces on parameter descriptions.
+- Fix spelling and grammar (`eg` → `e.g.`, `etc.` → `etc.`).
+- Proper acronyms: GUID, URL (not Guid, Url).
+- Consistent terminology (e.g. Adobe Asset Link).
+
+## Summaries
+
+- Sentence case; no trailing period; no `API` suffix.
+- Lowercase version labels: `v1`, `v2` (not `V1`).
+- Clear, descriptive; `operationId` in camelCase.
+
+## Public-facing text
+
+User-visible strings must not contain internal-only information.
+
+**Scan:** `info`, `tags`, operation summaries/descriptions, parameters, schemas, examples (prose), enum descriptions.
+
+**Do not allow:**
+
+- Jira or ticket keys (e.g. `FFENT-8796`, `PROJ-123`)
+- Internal codenames, internal service names, corp-only wiki URLs
+- Authoring TODOs tied to tickets (e.g. `TODO: fix after FFENT-…`)
+
+**Allowed:** Public product names, customer error codes, placeholders (`{your_api_key}`), standard field names (`jobId`).
+
+Flag violations as **high** severity in eval/review output. `/api-fix` does **not** auto-fix copy — use `/api-review` or explicit ref-based edits.

.cursor/rules/api-ref-examples.mdc

@@ -0,0 +1,23 @@
+---
+description: Request and response example values for Redocly OpenAPI docs
+globs: static/**/*.json
+alwaysApply: false
+---
+
+# API reference — examples
+
+## Values
+
+- Prefer realistic dummy values users can copy and run.
+- Avoid type placeholders like `"string"` when an example can be provided.
+- Use `{your_presigned_get_url}` style placeholders (curly brackets) when a real URL is impractical.
+
+## Placement
+
+- Short placeholders in example **values**.
+- Instructions ("Replace with your presigned GET URL…") in parameter or request-body **descriptions**, not inside example strings.
+
+## Patterns
+
+- Request: realistic URLs, `your-output.pdf`, plausible `jobId` UUIDs.
+- Response: show async shape (`jobId`, `statusUrl`, `status`) where applicable.

.cursor/rules/api-ref-ffs-styleguide.mdc

@@ -0,0 +1,67 @@
+---
+description: Firefly Services API Style Guide checkpoints for api-eval (not api-fix)
+globs: static/**/*.json
+alwaysApply: false
+---
+
+# Firefly Services API Style Guide (eval only)
+
+**Wiki:** [Firefly Services API Style Guide](https://wiki.corp.adobe.com/display/GenAI/Firefly+Services+API+Style+Guide)
+
+Use with `/api-eval` only. `/api-fix` does **not** apply these unless Redocly flags them.
+
+**Offline checklist:** [.cursor/skills/api-eval/ffs-styleguide-checklist.md](../skills/api-eval/ffs-styleguide-checklist.md)
+
+## Scope
+
+Stateless Firefly Services RPC APIs. POST → async; GET (collections, status) → sync.
+
+## HTTP and URLs
+
+- POST operations: async 202 pattern.
+- URL shape: `https://{subdomain}.adobe.io/v{version}/{operation-name}`.
+- POST paths: verb-led, hyphenated (e.g. `/v2/generate-object-composite`).
+- GET collections: plural nouns.
+
+## Async 202 response
+
+Required: `jobId`, `statusUrl`. Optional: `cancelUrl`. URLs: `…/v{version}/status/{jobId}`.
+
+## Status polling (GET)
+
+- `status`: `not_started`, `running`, `succeeded`, `failed`, `partially_succeeded`, `canceled`.
+- `jobId` on all status responses.
+- Failed: `error_code` or `errors[]` per Error Codes wiki.
+
+## Errors
+
+- 4xx/5xx and job failures: `error_code` required; `message` optional.
+- Codes from [Error Codes wiki](https://wiki.corp.adobe.com/display/GenAI/API+Style+Guide%3A+Error+Codes).
+
+## JSON conventions
+
+- Property names: camelCase (except `error_code`).
+- American English spellings.
+- Suffixes: `*Date`, `*MediaType`, `*LocaleCode`, `*Folder`; plural names for arrays.
+- Date-times: ISO 8601 with `Z`; locales: `en-US`.
+- Media types: `enum` in OpenAPI spec.
+- Omit null properties in responses (no `anyOf` with null for optional fields).
+
+## Resource objects
+
+Only: `url`, `uploadId`, or ACPC-related properties; optional `storageType` for Azure/Dropbox output URLs.
+
+## source / destination
+
+Recommended wrapper pattern for binary inputs/outputs with peer metadata.
+
+## POST → async (Jan 2026)
+
+Product POST endpoints should use the async calling pattern.
+
+## Severity
+
+- **error** — invalid OpenAPI or lint failure
+- **high** — style guide contract violation
+- **medium** — doc/copy vs modular rules
+- **low** — suggestion

.cursor/rules/api-ref-router.mdc

@@ -0,0 +1,35 @@
+---
+description: Route OpenAPI JSON work to api-eval, api-review, or api-fix skills
+globs: static/**/*.json
+alwaysApply: false
+---
+
+# API reference router
+
+When editing or reviewing OpenAPI JSON under `static/`, use the right skill. Load modular rules only when needed.
+
+## Task routing
+
+| User intent | Skill | Edits? |
+|-------------|-------|--------|
+| `/api-eval`, evaluate, audit | [api-eval](../skills/api-eval/SKILL.md) | No — findings only |
+| `/api-review`, catalog descriptions | [api-review](../skills/api-review/SKILL.md) | No — tables for manual review |
+| `/api-fix`, fix lint or structure | [api-fix](../skills/api-fix/SKILL.md) | Yes — **lint + api-ref-structure** |
+
+Resolve the spec path with [_shared/resolve-api-spec.md](../skills/_shared/resolve-api-spec.md). Do **not** assume `petstore.json`.
+
+## Non-negotiable description rule
+
+- **HTTP response `description`** (status lines): Title Case, **no** trailing period (e.g. `Internal Server Error`).
+- **All other descriptions** (operations, parameters, schemas, headers): complete sentences **with** periods.
+
+## Modular rules (load on demand)
+
+- `api-ref-structure.mdc` — section order, license, JSON/$ref
+- `api-ref-copy.mdc` — summaries, punctuation, public-facing text
+- `api-ref-schema.mdc` — anyOf, type arrays, $ref/title
+- `api-ref-examples.mdc` — Redocly examples
+- `api-ref-tags-errors.mdc` — tags, errors, auth
+- `api-ref-ffs-styleguide.mdc` — Firefly Services API Style Guide (api-eval only)
+
+Legacy monolith: `eval-API-ref.mdc` (deprecated stub).

.cursor/rules/api-ref-schema.mdc

@@ -0,0 +1,34 @@
+---
+description: OpenAPI schema patterns — anyOf, $ref, naming, OpenAPI 3.0 vs 3.1
+globs: static/**/*.json
+alwaysApply: false
+---
+
+# API reference — schemas
+
+## Naming
+
+- Schemas: PascalCase, descriptive (e.g. `RemoveBackgroundRequest`).
+- Properties: camelCase.
+- Paths: descriptive kebab-case (e.g. `/v2/remove-background`).
+
+## anyOf
+
+- **Do not** use `anyOf` when the only alternative is `null` — omit from `required` instead.
+- **Do not** use `anyOf` with a single option — use direct `$ref` or type.
+- **Valid anyOf:** multiple real type alternatives (not null-only).
+
+## OpenAPI 3.1 only
+
+- Simplify primitive `anyOf` to type arrays: `"type": ["string", "array", "null"]`.
+- OpenAPI **3.0** does not support multi-value type arrays — do not apply 3.1 patterns to 3.0 files.
+
+## $ref siblings
+
+- **Remove** `title` as sibling to `$ref` (ignored by tools, linter errors).
+- **Keep** `description`, `deprecated`, `example` siblings where tools support them.
+- Put titles on the referenced schema definition instead.
+
+## Organization
+
+- Group related schemas; avoid duplicates; use `$ref` (DRY).

.cursor/rules/api-ref-skills.mdc

@@ -0,0 +1,21 @@
+---
+description: Points to /api-eval, /api-review, and /api-fix skills for OpenAPI JSON in static/
+globs: static/**/*.json
+alwaysApply: false
+---
+
+# API spec skills (`/api-eval`, `/api-review`, `/api-fix`)
+
+Agent skills for OpenAPI JSON under `static/`. Resolve the spec path with [_shared/resolve-api-spec.md](../skills/_shared/resolve-api-spec.md) — **no** `petstore.json` default.
+
+| Command | Skill | Edits? |
+|---------|-------|--------|
+| **`/api-eval`** | [api-eval/SKILL.md](../skills/api-eval/SKILL.md) | No — audit findings |
+| **`/api-review`** | [api-review/SKILL.md](../skills/api-review/SKILL.md) | No — description catalog tables |
+| **`/api-fix`** | [api-fix/SKILL.md](../skills/api-fix/SKILL.md) | Yes — Redocly lint + structure fixes |
+
+**Agent:** [api-spec-reviewer.md](../agents/api-spec-reviewer.md) — runs lint + api-fix after OpenAPI edits.
+
+**Lint:** `npm run lint:openapi -- static/your-spec.json` · `npm run lint:openapi:all`
+
+**FFS style guide wiki:** [Firefly Services API Style Guide](https://wiki.corp.adobe.com/display/GenAI/Firefly+Services+API+Style+Guide)

.cursor/rules/api-ref-structure.mdc

@@ -0,0 +1,43 @@
+---
+description: OpenAPI file structure, section order, license, and JSON validity
+globs: static/**/*.json
+alwaysApply: false
+---
+
+# API reference — structure
+
+## Section order
+
+Top-level keys in this order:
+
+1. `openapi` (version, always first)
+2. `info` (include `license` when missing)
+3. `servers`
+4. `security`
+5. `tags`
+6. `paths`
+7. `components` (always last)
+
+## License boilerplate
+
+When `info.license` is missing, add:
+
+```json
+"license": {
+  "name": "Adobe Creative API License",
+  "url": "https://www.adobe.com/content/dam/cc/en/legal/terms/enterprise/pdfs/PSLT-AdobeCreativeAPI-WW-2024v2.pdf"
+}
+```
+
+## Validity
+
+- Valid JSON syntax.
+- All `$ref` paths resolve to existing schemas.
+- No duplicate schema names in `components.schemas`.
+- Verify `openapi` version (3.0.x vs 3.1.x) before applying version-specific schema rules.
+
+## File organization
+
+- Group related endpoints (operation + status) together.
+- Organize schemas by function or alphabetically.
+- Consistent indentation.

.cursor/rules/api-ref-tags-errors.mdc

@@ -0,0 +1,43 @@
+---
+description: OpenAPI tags, standard error responses, and authentication parameters
+globs: static/**/*.json
+alwaysApply: false
+---
+
+# API reference — tags, errors, auth
+
+## Tags
+
+- Descriptive sentence-case names with descriptions.
+- Order logically; core operations first (e.g. "Common operations").
+- No empty tag arrays; avoid generic tags (`API`, product name only).
+
+## Standard error responses
+
+Include where appropriate:
+
+| Code | Description |
+|------|-------------|
+| 400 | Bad Request or Input Validation Error |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Requested Resource Was Not Found |
+| 429 | Too Many Requests |
+| 500 | Internal Server Error |
+
+Use Title Case, no periods on response descriptions.
+
+## Error schema
+
+- `error_code` (snake_case, gateway-aligned) and optional `message` on error payloads.
+
+## Authentication
+
+- Document `Authorization` (Bearer) as required.
+- Document `x-api-key` as optional where Cluster Gateway applies.
+- Consistent parameter naming across operations.
+
+## Versioning
+
+- Summaries include version: `Remove background v1`, `Get status - v2`.
+- Beta: `v2 (beta)`; lowercase `vN`.

.cursor/rules/cursor-rules.mdc

@@ -33,7 +33,10 @@ Never place rule files:
 
 ## Project Agent skills (optional)
 
-**Rules** (this folder) are always-on or glob-scoped instructions for the agent. **Skills** live under `PROJECT_ROOT/.cursor/skills/<skill-name>/SKILL.md` and describe fuller workflows (for example stage-all-and-commit). If you add a skill, consider a short companion rule or a line in this file so contributors know it exists. For Git helpers: **`/gc`** commits after staging; **`/gcam`** stages, proposes a message, and waits for commit vs reject—see [.cursor/rules/gc-commit-skill.mdc](gc-commit-skill.mdc), [.cursor/skills/gc/SKILL.md](../skills/gc/SKILL.md), and [.cursor/skills/gcam/SKILL.md](../skills/gcam/SKILL.md).
+**Rules** (this folder) are always-on or glob-scoped instructions for the agent. **Skills** live under `PROJECT_ROOT/.cursor/skills/<skill-name>/SKILL.md` and describe fuller workflows (for example stage-all-and-commit). If you add a skill, consider a short companion rule or a line in this file so contributors know it exists.
+
+- **Git:** **`/gc`** · **`/gcam`** — [.cursor/rules/gc-commit-skill.mdc](gc-commit-skill.mdc), [.cursor/skills/gc/SKILL.md](../skills/gc/SKILL.md), [.cursor/skills/gcam/SKILL.md](../skills/gcam/SKILL.md)
+- **OpenAPI JSON (`static/`):** **`/api-eval`** · **`/api-review`** · **`/api-fix`** — [.cursor/rules/api-ref-skills.mdc](api-ref-skills.mdc); agent [.cursor/agents/api-spec-reviewer.md](../agents/api-spec-reviewer.md)
 
 ## Naming conventions