fix(author): the skill follows the owner's flow, and every content type's file names the source's own fields

Merged
AL
6h ago
+152-7

Closes #182. Closes #184.

The owner's ChatGPT run on 0.9.1, given the skill's link, wrote a quiz's source without authors, which the build refuses (#182). Every content type refuses a source without title, language, license or authors (checked by building each of the 28 the skill lists with params alone). But every type file's example is type and params only, and since #181 a chat reads the type file and copies it. The types' own required fields were never the gap: each type file's generated Fields section marks them.

The owner then set the flow the skill follows (#184): the content type, chosen with the user; then the author and licence, which the user fills or skips (a known name or a default); then the source; then the best way to build it for the situation, in the app or by a link to the build page.

What changes

  • SKILL.md writes the order out before step 1, one question at a time.
  • Step 1 proposes one or two types and waits, unless the user named a type from the table: "a quiz" or "flash cards" names none. Once the user has chosen, it asks in a message of its own for the author's name and the licence, only for what they have not given yet, and says they may skip. What they gave stays as they gave it. A name they skip is the one the model knows them by, or "Unknown"; a licence they skip is U (undisclosed). Never a name made up for them. That each value's skip is its own was cubic's second review, bf9d0be.
  • Step 2 opens by naming the four fields every source has, whatever a type file's example leaves out.
  • Step 3 opens with the three ways to build and what each needs: here with npm, here from two files (ChatGPT), or in the user's browser through the build page with no attempt here first (Gemini, a chat with no tools). The model takes the first that applies and tells the user which.
  • Every content type's file says the same in its generated section, SOURCE_FIELDS, written by schemaMarkdown for content types and not parts: "The example is type and params alone, and params holds the fields below. A source also names its own title, language, license and authors, all four required: the build refuses a source that leaves out any of them. The author's name and the licence are the user's: ask for what they have not given. For a name they skip, write the one you know them by, or "Unknown"; for a licence they skip, U." The example is labelled rather than given the four fields: a name written in it would be copied as the author and build. That was cubic's review, 31d0989. sync:skill wrote the line into the 28 content types' files; Image, Text, AdvancedText and Video are unchanged. A chat with no skill at all gets it too, in the type file the build page hands over.
  • The brief asks for the author and licence once the type is chosen, with the same skip, each value's own.
  • design/author.md says why, and what was measured.

Tested

  • pnpm --filter @missing-elements/h5p-author test:unit passes, 179 tests, and so does the typecheck. The new test fails when the line goes into a part's file too (tried).
  • pnpm --filter @missing-elements/h5p-skills test passes, 77 tests: every type file is current with the generator, and every example builds and plays.
  • Haiku, in the chat stand-in: a fetch tool that opens only addresses seen whole, npm cut off, and a scripted user who answers when asked.
    • Author only, 0.9.1's text, a Question Set named: 2 of 3 runs asked for the author, from the brief's list. The third wrote "Quiz author" and built.
    • The flow, a quiz asked for with neither type nor author named: before step 1 said "a quiz" names no type, 4 of 6 runs chose the Question Set themselves, 3 of them asking for the author in the same message. With the final text, 4 of 4 proposed two types and waited, then asked for the author and licence on their own. The two that were given a name wrote it, and the two that were skipped wrote "Unknown" and U. Every package passes h5p-verify.
    • A skip of one value only (cubic's second review): the text that wrote the skip for both at once did not go wrong in 3 runs: a name and no licence, a licence and no name, and the author named in the request with the licence skipped. With the final text, 5 of 5 (those three, both skipped, both given) wrote what was given and the default for what was skipped, and the run with the author named in the request asked for the licence alone. All eight packages pass h5p-verify.
  • Not this PR's change: in 4 of 10 flow runs, the model wrote <p> tags into Question Set's overall feedback, a plain-text field. The build noted it, and the run rebuilt once.

To release

h5p-author 0.9.2, a patch: the skill's text and the type files' generated section. schema --markdown prints the new line for a content type. Then the site's pin moves to it, for /h5p/skill/ and the build page's type files. Installed copies need npx skills update -g and a new upload to the Claude app.