keryx theme migrate¶

Description¶

Brings your theme catalog up to date, in two independent moves:

out of the legacy ~/.keryx/config.yaml into ~/.keryx/themes.yaml (spec 0042 §3.6);
out of the per-type shape into one flat list (spec 0047).

Either may already be done. It reports only what it actually changes.

Usage¶

keryx theme migrate [--dry-run] [--default <keyword>]

Run keryx theme migrate --help for the authoritative, always-current flag set.

Nothing moves until you ask¶

This is a command rather than something that happens on first run. Silently rewriting files you own, at a moment you did not choose, is the kind of surprise that erodes trust in every later write. keryx doctor tells you there is something to do and leaves the timing to you.

Look before you leap¶

$ keryx theme migrate --dry-run --default editorial
flattened to 13 theme(s), one list
default: editorial

merged (the same keyword under more than one type):
  blueprint    article + reel
  clay         article + reel
  editorial    article + reel

worth renaming — meaningless in a flat list:
  default

these styles still describe framing or aspect, which the target now
supplies. Left exactly as written — trim them by hand when you like:
  tattoo       16:9, banner, negative space, centred, no text
  emberlight   vertical, no text

nothing was written — re-run without --dry-run to apply

Three things worth reading there:

Merged — the same keyword filed under two types becomes one theme carrying both sides' fields. The article side's cover prompt and the reel side's music and voice both survive; nothing is discarded.
Worth renaming — a keyword like default made sense inside a portrait: block and means nothing in a flat list, especially sitting beside themes.default, which now means something else entirely.
Framing — the phrases are listed, not just the theme names, because nearly every style mentions something. tattoo 16:9, banner tells you what to delete; emberlight vertical is nearly clean already.

Nothing in your prose is edited. A tool that rewrites words you wrote is a tool you stop trusting with words.

`--default` when your defaults disagree¶

Themes now have a single default rather than one per type. If your existing per-type defaults differ, migration stops rather than choosing for you:

$ keryx theme migrate
ERRO your per-type defaults differ (article=editorial, portrait=default,
     reel=editorial) and there is now a single default — re-run with
     `--default <keyword>` to choose which one applies to every target

The default decides what every un-themed generation produces, so picking one on your behalf would change output you never asked to change.

What it does and does not touch¶

Only themes move. Your config.yaml keeps its other job — ports, update policy, git behaviour — untouched.
A theme already in the library is left alone. One promoted from a project after the legacy copy was written is the newer version, and overwriting it with a stale duplicate would undo deliberate work.
The destination is written first, and the source cleared only once that succeeded — so a failure leaves a recoverable duplicate rather than nothing.

You do not have to run it immediately¶

An unmigrated catalog keeps working: keryx reads the legacy file as a lower-precedence layer, and resolves the per-type shape and the old per-type defaults exactly as before. Migrating is what stops the old shape being the real one.