Upgrading a wskill to a new base schema

§ 1Purpose

Move an existing wskill onto a newer wskill base schema without losing content.

§ 2Prerequisites

• A newer wskill scaffold is available (a newer wcl release).

§ 3Flowchart

§ 4Steps

$ wcl init wskill /tmp/wskill-ref --defaults
$ diff schema/base.wcl /tmp/wskill-ref/schema/base.wcl

Scaffold a throwaway wskill with the new wcl and diff its schema/base.wcl against yours — that diff IS the upgrade. Check the header's Schema version: line for how far apart you are.

If the new base imports topic-owned files you don't have yet (e.g. schema/kinds.wcl), copy them from the reference scaffold BEFORE replacing base.wcl — a base that imports a missing file fails wcl check with a confusing unknown-type error. Your existing kinds.wcl/extensions.wcl are yours; keep them and merge any new baseline entries.

$ cp /tmp/wskill-ref/schema/base.wcl schema/base.wcl
# template sets only if you never customised them:
$ diff -r wdoc/ /tmp/wskill-ref/wdoc/

Overwrite schema/base.wcl with the new one (it is generated — never hand-merged). Diff the wdoc/ template sets too: take the new ones wholesale if you never customised them, otherwise port the diff into your customised copies.

$ wcl check wskill.wcl        # every violation, file + line

Run wcl check and fix what it reports — renamed fields, newly constrained values (e.g. a free-text entity kind becoming a :symbol from kinds.wcl), new required fields. The errors are the migration checklist.

$ just render && just book-serve

Set schema_version in wskill.wcl to the new base's version, re-render every shipped view, and spot-check the book. Commit the upgrade as one change.