# ISIS v2 Foliage Pack Operator/Creator Documentation with Troubleshooting

Generated: 2026-03-02T06:52:05.021Z Checklist: `MXA-0396` (ISIS2-00594) Asset
Family: `foliage-pack` Phase: Phase 4 | Milestone: M3 Launch (2026-07-27 to
2026-10-30)

## Objective

Publish creator and operator documentation with troubleshooting for foliage-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=65, validationRules=36 |
| `operator` | Guardrails, regression, integration and runbook diagnostics | envKeys=15, troubleshooting=6   |

## Workflow Coverage

| Workflow                           | Creator UI Documentation | Operator Policy Documentation | Troubleshooting Coverage |
| ---------------------------------- | ------------------------ | ----------------------------- | ------------------------ |
| `foliage-pack-baseline`            | yes                      | yes                           | yes                      |
| `foliage-pack-image-conditioned`   | yes                      | yes                           | yes                      |
| `foliage-pack-control-conditioned` | yes                      | yes                           | yes                      |
| `foliage-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`              | `FOLIAGE_PACK_BUDGET_GUARDRAIL_LIMIT_EXCEEDED`  | `operator` | yes             |
| `quality-gate-failed`                     | `FOLIAGE_PACK_QUALITY_GATE_FAILED`              | `operator` | yes             |
| `regression-consistency-drift`            | `regression-foliage-pack-consistency-drift`     | `operator` | yes             |
| `regression-output-package-contract-miss` | `regression-foliage-pack-package-contract-miss` | `operator` | yes             |
| `downstream-trigger-integration-drift`    | `workflow-trigger-endpoint-mismatch`            | `operator` | yes             |

## Creator Quickstart

- Select the foliage-pack workflow variant that matches the shot intent and
  control profile.
- Complete required foliage profile fields (foliage theme, biome context, canopy
  structure, species mix, density class, branch complexity, wind response,
  seasonality, tiling mode, seam blend strategy, foliage resolution class, seed)
  and any conditional controls before submit.
- Use side-by-side output comparison to verify seam continuity, canopy coverage
  consistency, species mix adherence, and foliage palette stability before
  approval.
- Export to downstream engine or DCC targets using recipe metadata for
  asset-family traceability.

## Operator Diagnostics Surface

- `X-Foliage-Pack-Estimated-Cost-Usd`
- `X-Foliage-Pack-Budget-Guardrail-Mode`
- `X-Foliage-Pack-Budget-Guardrail-Reason`
- `X-Foliage-Pack-Quality-Gate-Mode`
- `X-Foliage-Pack-Quality-Gate-Reason`
- `X-Foliage-Pack-Quality-Failing-Metrics`

## Verification Commands

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

## Acceptance Criteria

- Creator documentation covers all foliage-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-0396`
- Ticket key: `ISIS2-00594`
- Linked checklist dependencies: `MXA-0387`, `MXA-0388`, `MXA-0389`, `MXA-0392`,
  `MXA-0393`, `MXA-0394`, `MXA-0395`
