Change a channel's theme

# Change a channel's theme

Use one read and one apply workflow to change tone and primary colors. Examples are illustrative inputs and must use current read results.

## Read the intended channel

Select a known channel code through the [directory guide](channel-directory.md) or the bound hosted resource, then call [design_theme_get](../tools/publ_design_theme_get.md):

```json
{"channelCode":"selected-channel-code"}
```

The HTTP implementation needs the selected channel's credential, an OWNER/DELEGATEE account role, and the operator-configured CHANNEL_ENV origin. Hosted theme tools belong to the selected-channel resource. Do not supply credentials or guessed API origins as business inputs.

Inspect `initialized`, tone, custom/effective colors, and `revision`. Missing settings return calculated DARK defaults without creating anything. The revision covers the complete palette, including keys not shown by the get result.

## Prepare the requested change

Pass get's `channel.channelCode` and `revision` into [design_theme_apply](../tools/publ_design_theme_apply.md). Include only intended changes. Omitted values are preserved; empty color strings reset overrides. Changing tone alone keeps custom colors.

```json
{
  "requestId":"example-theme-reset-001",
  "channelCode":"selected-channel-code",
  "expectedRevision":"0000000000000000000000000000000000000000000000000000000000000000",
  "tone":"LIGHT",
  "brandColor":"",
  "onBrandColor":"",
  "dryRun":true
}
```

This example requests LIGHT tone and both default colors. Replace the placeholder code/revision with the actual read values. For a custom color use `#RGB` or `#RRGGBB`. A connected server may still predate this correction: inspect its discovery schema and use lowercase hex digits for a new request if it advertises the older lowercase-only pattern. Preserve the exact inputs when resuming an existing request ID. At least one tone/color field is required.

A new dry run returns the requested change and whether initialization is required. When settings exist it includes planned patches; missing settings have no patch list until real initialization supplies defaults. No new job or task ID is saved by this dry run.

## Apply and verify

Execute the same request ID and business inputs with `dryRun:false` when the plan matches the requested operation. The workflow initializes missing settings, writes tone if needed, then writes the full palette while preserving other keys. It reads after changes and checks the final full theme.

`DESIGN_THEME_APPLIED` with `verification.confirmed:true` means expected stored values were observed. Equivalent hex spellings can avoid a color step. `changed:false` can still follow initial settings creation; do not interpret that flag alone as zero writes.

The steps are not atomic. An earlier tone change can remain when a palette update fails. Revisions cannot prevent every competing write after the last check, and there is no automatic rollback.

## Inspect and resume

Preserve the returned task identity. Call [task_status](../tools/publ_task_status.md) with the actual original ID:

```json
{"taskId":"example-theme-reset-001","taskType":"design-theme"}
```

If continuing the original operation is intended, pass the same pair to [task_resume](../tools/publ_task_resume.md). A definite rejection/not-sent step can resume after its cause is resolved. An uncertain initialization or update is observed first and is not resent if the result remains unknown. Inspect the original task before considering any new plan; never change the ID to force a retry.

Completed results are historical. Apply/resume can check channel context while returning an old theme result, so use get for current theme values. An observed matching state does not prove which actor created or changed it.

[Reference index](../index.md) · [Theme get](../tools/publ_design_theme_get.md) · [Theme apply](../tools/publ_design_theme_apply.md) · [Common results](../reference/results.md)

## Saved plan replay

An existing matching task's `dryRun` returns historical saved plan/progress,
`historical:true`, `replayed:true` and false current verification. It has no current
console/action link and does not read present business state, repeat effects or
change the journal. Saved phase/progress and existingPhase aliases remain where
applicable. Follow `nextStep` for a current observation; retain the original task
ID for uncertain-outcome recovery. A new task keeps normal fresh-plan validation.

`nextStep`: design_theme_get retains the original channel; saved tone/palette steps are not a fresh theme read.

## Saved record identity

For this workflow, existing apply/dry-run calls and task status/resume require
both the saved task ID and saved input requestId to match the requested ID.
A mismatching or malformed saved identity returns `TASK_STATE_UNVERIFIED` before
workflow context or business-state reads. Preserve the original record for
inspection; do not rename/edit it, try its embedded ID or create a replacement
request to bypass the error. No stored record is repaired or resent. Valid
matching records retain the recovery behavior described above.

## Saved step consistency

Existing theme tasks must retain the original input fingerprint, derived ordered
patches, preserved palette values, progress and expected final state. Inconsistent
records return `TASK_STATE_UNVERIFIED` before context/business calls and remain
unchanged. Generic missing/invalid completion still uses
`TASK_COMPLETION_UNVERIFIED`. Historical success is not a fresh theme observation.