# ISIS v2 NPC Crowd Variation Pack Operator/Creator Documentation with Troubleshooting

Generated: 2026-08-02T17:39:32.120Z Checklist: `MXA-0108` (ISIS2-00306) Asset
Family: `npc-crowd-variation-pack` Phase: Phase 4 | Milestone: M3 Launch
(2026-07-27 to 2026-10-30)

## Objective

Publish creator and operator documentation with troubleshooting for
npc-crowd-variation-pack workflows, spanning workflow authoring, guardrail
operations, regression diagnostics, and downstream integration remediation.

## Persona Coverage

| Persona    | Workflow Focus                                              | Coverage Signals                |
| ---------- | ----------------------------------------------------------- | ------------------------------- |
| `creator`  | Workflow authoring, variant controls, typed submission      | controls=52, validationRules=30 |
| `operator` | Guardrails, regression, integration and runbook diagnostics | envKeys=15, troubleshooting=6   |

## Workflow Coverage

| Workflow                                       | Creator UI Documentation | Operator Policy Documentation | Troubleshooting Coverage |
| ---------------------------------------------- | ------------------------ | ----------------------------- | ------------------------ |
| `npc-crowd-variation-pack-baseline`            | yes                      | yes                           | yes                      |
| `npc-crowd-variation-pack-image-conditioned`   | yes                      | yes                           | yes                      |
| `npc-crowd-variation-pack-control-conditioned` | yes                      | yes                           | yes                      |
| `npc-crowd-variation-pack-consistency-locked`  | yes                      | yes                           | yes                      |

## Troubleshooting Matrix

| Issue                                     | Signal                                                     | Persona    | Source Coverage |
| ----------------------------------------- | ---------------------------------------------------------- | ---------- | --------------- |
| `creator-contract-validation-failure`     | `INVALID_WORKFLOW_RUN_REQUEST`                             | `creator`  | yes             |
| `budget-hard-limit-exceeded`              | `NPC_CROWD_VARIATION_PACK_BUDGET_GUARDRAIL_LIMIT_EXCEEDED` | `operator` | yes             |
| `quality-gate-failed`                     | `NPC_CROWD_VARIATION_PACK_QUALITY_GATE_FAILED`             | `operator` | yes             |
| `regression-consistency-drift`            | `regression-npc-crowd-consistency-drift`                   | `operator` | yes             |
| `regression-output-package-contract-miss` | `regression-npc-crowd-package-contract-miss`               | `operator` | yes             |
| `downstream-trigger-integration-drift`    | `workflow-trigger-endpoint-mismatch`                       | `operator` | yes             |

## Creator Quickstart

- Select the npc-crowd-variation-pack workflow variant that matches the shot
  intent and control profile.
- Complete required archetype/style/seed fields and any conditional control maps
  before submit.
- Use side-by-side output comparison to verify identity/style consistency before
  approval.
- Export to downstream engine or DCC targets using recipe metadata for
  asset-family traceability.

## Operator Diagnostics Surface

- `X-Npc-Crowd-Variation-Pack-Estimated-Cost-Usd`
- `X-Npc-Crowd-Variation-Pack-Budget-Guardrail-Mode`
- `X-Npc-Crowd-Variation-Pack-Budget-Guardrail-Reason`
- `X-Npc-Crowd-Variation-Pack-Quality-Gate-Mode`
- `X-Npc-Crowd-Variation-Pack-Quality-Gate-Reason`
- `X-Npc-Crowd-Variation-Pack-Quality-Failing-Metrics`

## Verification Commands

- `pnpm --filter @isis/web exec vitest run src/pages/npc-crowd-variation-pack-ui-utils.spec.ts src/pages/WorkflowDetailsPage.spec.tsx`
- `pnpm --filter @isis/generation-api exec vitest run src/routes/npc-crowd-variation-pack-budget-utils.spec.ts src/routes/npc-crowd-variation-pack-quality-gate-utils.spec.ts src/routes/npc-crowd-variation-pack-regression-golden-dataset.spec.ts`
- `pnpm --filter @isis/client exec vitest run src/examples/external-integrations.spec.ts src/examples/npc-crowd-variation-pack.spec.ts`

## Acceptance Criteria

- Creator documentation covers all npc-crowd-variation-pack workflow variants,
  required controls, validation constraints, and typed SDK run paths.
- Operator documentation covers budget and quality guardrail policies, required
  environment keys, regression diagnostics, and monitoring headers.
- Troubleshooting matrix includes creator-input, budget, quality, regression,
  and downstream integration remediation flows with concrete source
  traceability.
- Published documentation remains reproducible through generator/validator
  scripts and evidence-linked governance artifacts.

## Traceability

- Checklist item: `MXA-0108`
- Ticket key: `ISIS2-00306`
- Linked checklist dependencies: `MXA-0099`, `MXA-0100`, `MXA-0101`, `MXA-0104`,
  `MXA-0105`, `MXA-0106`, `MXA-0107`
