The agent cannot find visualize
Reload your agent after installation, then ask it to list available skills. Check that the installation directory contains visualize/SKILL.md and its referenced files.
Two copies are installed
Ask the agent which copy it uses. Choose a project-local or user-level installation, then approve removal of the unused copy.
The document ignores your brand
Ask which project guidance the agent used and whether it applied an exception for this document. Correct any unintended exception before requesting more edits.
To record missing project guidance, use teach. Review the proposed files before approving the write. Keep credentials and confidential customer data out of design guidance.
Explore asks for a design system
Check that the active installation is v0.8.0. Older instructions required an existing design system. Artifact Explore can start from your content without a layout or project design files. It still uses available project guidance.
Styling proposed for one document does not become the project's design system. Use teach to record an existing project identity, or System Explore to compare a new or replacement identity.
A theme conflicts with project styling
Say that the theme applies only to this document and name what must stay fixed. Project guidance applies unless you approve an exception. Applying a theme does not authorize changes to project design files.
Color feedback changes the wrong thing
Name the change: hue, lightness, saturation, colored area, or placement. Ask for an unchanged version alongside the alternatives. Specify any brand colors, chart categories, layout, or typography to preserve.
A red brand color, a multicolor chart, or a neutral gray surface does not need changing just to satisfy a style rule. Check contrast and keep labels or other cues wherever color carries meaning.
A comparison direction failed its checks
A direction fails if it changes fixed content, assets, or behavior; affects another direction's styling; contains incomplete HTML; or does not offer a meaningful alternative.
Ask the agent to correct or rebuild it. The original document stays unchanged. A failed direction does not authorize reducing the agreed number of alternatives or selecting another one for you.
The comparison crops the document
Ask the agent to remove fixed-height containers and nested scrolling. Switching between desktop and phone widths should show the full document with normal page scrolling.
The original file changed during review
Before applying a direction, the agent rereads the original file and project guidance. If either has changed, it stops so you can reconcile the newer work with your selection. Do not overwrite newer work from an old comparison.
Installation asks to publish something
Stop the setup. Installation does not create documents, sign in, or publish. Report the problem in GitHub Issues.
Image generation needs an API key
For the OpenAI or Gemini API, first select the provider, then configure OPENAI_API_KEY or GEMINI_API_KEY in your 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
Do not immediately retry or switch providers. After a timeout, connection loss, rejection after submission, malformed image, or unexpected bridge exit, the provider may already have generated and billed the image. This applies to the supported generation methods and any separately reviewed local method.
Ask the agent for the error code and any retained temporary-file directory. Decide whether to investigate the first attempt or deliberately start a new one.
If generation could not start because of a missing key, missing executable, or confirmed lack of support, the agent can offer other methods for you to select. Optional imagery can be omitted. If the approved design requires imagery, creation stops with setup instructions.
After an unexpected bridge exit, temporary files may remain in the project directory named in the error. Confirm that the child process has stopped before inspecting them. After recovery, remove that exact directory; it contains copies of your prompt and reference images.
Image generation reports success but the image is missing
Treat the request as failed. Success requires one PNG or JPEG at the requested path, details of the generation method and output, and visual inspection by the active agent. The agent must ask before replacing an existing image.
If the output is locked, inspect the adjacent .visualize.lock JSON for its process ID and creation time. Remove that exact lock only after confirming that the named local process is no longer running.