Skip to content

docs: teach the theme skill formatVersion and themes that can't load - #23

Merged
omartelo merged 2 commits into
mainfrom
docs/theme-format-version
Sep 13, 2026
Merged

omartelo merged 2 commits into
mainfrom
docs/theme-format-version

Conversation

@omartelo

@omartelo omartelo commented Sep 13, 2026 •

Copy link
Copy Markdown
Collaborator

Follow-up to lichdotdev/lich#598 and lichdotdev/lich#600. Depends on both shipping in a release: until #598 a lich in the wild still logs broken themes instead of listing them, and until #600 it ignores minLichVersion and a manifest formatVersion.

What changes

  • skills/theme/SKILL.md: the rules list gains formatVersion (optional, omitted means 1, positive integer no greater than the format lich reads, refused by number). The Traps bullet about copying a file into the themes directory now says a broken stored theme is listed under the theme strip as one that can't load, with the reason and Remove, after a window reload; only a file whose name is not a valid theme id stays log-only. Import is still the path that selects the theme. The frontmatter description drops "silently missing" in favor of "listed as a theme that can't load, or missing".
  • skills/theme/validate.mjs: accepts formatVersion 1, rejects a non-integer or < 1 ("must be a positive integer") and a newer format with lich's wording ("theme format 2 is newer than this lich reads (up to 1); update lich").
  • template.json unchanged: nothing in this repo's tests or CI requires the key, and lich stamps it on install.
  • lich#600: the repository rules gain the optional manifest fields minLichVersion (MAJOR.MINOR.PATCH, older lich refuses, dev builds skip; suggested when a pack uses a token only a recent lich has) and formatVersion (same rule as a theme file, error prefixed manifest: ). validate.mjs checks their shape; whether the running lich is new enough stays lich's call.
  • CHANGELOG [Unreleased] entries.

Test plan

  • validate.mjs on a template-derived theme with formatVersion absent, 1 (ok), 2, 0, 1.5, "1" (rejected with the expected messages)
  • validate.mjs on a repository with manifest minLichVersion absent / 0.51.0 (ok), 0.51 / 51 (rejected), manifest formatVersion 2 / "1" (rejected, manifest: prefix)
  • node --test tests/*.test.mjs (hook contract tests green in CI)
  • fixtures match lich fails on this PR for an unrelated reason: upstream session-start.jsonl gained a line since v0.12.0; left for its own change, since the scripts have to match it first

lich#598 adds an optional formatVersion to theme files and lists a stored
theme it cannot load in Settings > Appearance instead of only logging it.
lich#600 adds both as optional fields of lich-theme.json.
@omartelo
omartelo merged commit 5e393ea into main Sep 13, 2026
3 of 5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant