# Troubleshooting

> Find the installed skill, resolve duplicate copies, and verify that the current agent can discover it.

## The agent cannot find visualize

Reload the host after installation, then ask it to list discovered skills. Confirm the selected host path contains `visualize/SKILL.md` and referenced files.

## Two copies are installed

Do not delete either copy blindly. Ask the agent which search path wins, choose project-local or user-level scope, then approve removal of the shadowed copy.

## The output ignores the project brand

Ask which project guidance and artifact exceptions the agent applied. Correct an unintended override before refining the file. If the project guidance needs recording, run `teach` and review its proposed files before approving writes. Do not paste credentials or confidential customer data into brand context.

## Artifact Explore asks for a design system

Confirm the active installation is v0.5.1. Older instructions required an existing visual system. The current workflow can start without a supplied layout or persisted profile, while respecting available project guidance. A temporary starting point or an artifact theme does not create project authority. Use `teach` when you want that authority recorded, not as a mandatory prerequisite for exploration.

## A requested theme conflicts with project styling

State whether the exception applies only to this artifact, and name what must remain fixed. Without an explicit exception, project guidance stays binding. Applying a theme does not authorize writing project design files.

## Color feedback changes the wrong thing

Be specific about the open dimension: hue, lightness, chroma, coverage, or placement. Ask for a fixed baseline and preserve the approved primary, category mappings, layout, and typography where relevant. Red is not reserved globally for destructive states; meaningful multicolor charts and neutral gray surfaces should not be recolored solely to satisfy a style rule. Contrast and non-color meaning still require verification.

## A candidate was rejected

The coordinator rejects a direction when it drops or rewrites fixed content, changes fixed assets or behavior, leaks styles into another direction, produces incomplete HTML, or fails to offer a meaningful difference on the open design question. The target remains unchanged. Correct or rebuild that direction; do not reduce the approved count or select another direction automatically.

## The comparison file crops the document

Artifact Explore changes review width, not document height. Ask the agent to remove fixed-height containers or nested scrolling from the review harness so the selected direction grows to its full height and the outer page scrolls normally.

## The target changed after the brief

The agent re-reads the target and design authority before applying a selected direction. If either changed during review, it stops so you can reconcile the newer source with the selection. Do not overwrite newer work from an old comparison.

## Installation wants to publish something

Stop. The setup runbook explicitly prohibits creation, sign-in, and publishing. Report the problem in [GitHub Issues](https://github.com/display-dev/visualize/issues).

## An image route needs an API key

The OpenAI and Gemini API routes are released only after you explicitly select one and configure its canonical `OPENAI_API_KEY` or `GEMINI_API_KEY` in the local environment. Never paste a key into chat, an image prompt, a project file, or a command argument.

## Image generation timed out or returned an invalid file

This recovery applies to the released Claude Code Codex MCP bridge, authenticated Codex CLI bridge, released OpenAI and Gemini API routes, a maintainer acceptance run, or another explicitly reviewed local candidate. Do not immediately retry or switch providers. A timeout, connection loss, provider rejection after submission, malformed image, or unknown bridge termination is ambiguous: the provider may already have generated and billed the request. Ask the agent to report the error code and any retained staging path, then decide whether to investigate or deliberately start a new attempt.

A missing key, missing executable, or confirmed pre-generation capability failure is different: no generation was observed, so the agent can present the remaining routes for you to select. Optional imagery can be omitted. If imagery is essential to the approved design, creation stops with setup guidance.

When an unconfirmed bridge termination retains staging, the structured error names its project-relative directory. Confirm the child process has stopped before inspecting it, then remove that exact directory after recovery; it contains the prompt and reference copies.

## The image route reported success but the image is missing

Treat the operation as failed. A successful workflow ends with one bounded PNG or JPEG at the matching requested path, returns route/output diagnostics, and requires the active agent to open and visually inspect the file. Existing output is not overwritten unless you approve replacement.

If the output is locked, inspect the adjacent `.visualize.lock` JSON for its PID and creation time. Remove only that exact lock after confirming the named local process is no longer running.