@lincyaw/skills 1.0.0-rc.2 → 1.0.0-rc.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/README.md +1 -1
  2. package/package.json +2 -3
  3. package/skills/index.json +9 -18
  4. package/skills/presmium-animate/SKILL.md +4 -2
  5. package/skills/presmium-animate/gallery/algorithms/lecture.json +171 -115
  6. package/skills/presmium-animate/gallery/anime/scenes/kmeans-seeded.ts +2 -1
  7. package/skills/presmium-animate/gallery/craft/lecture.json +109 -57
  8. package/skills/presmium-animate/gallery/data/lecture.json +711 -175
  9. package/skills/presmium-animate/gallery/emphasis/lecture.json +321 -79
  10. package/skills/presmium-animate/gallery/films/lecture.json +36 -10
  11. package/skills/presmium-animate/gallery/lengths/lecture.json +23 -88
  12. package/skills/presmium-animate/gallery/math-ml/lecture.json +238 -159
  13. package/skills/presmium-animate/gallery/paths-3d/lecture.json +74 -64
  14. package/skills/presmium-animate/gallery/product/lecture.json +27 -3
  15. package/skills/presmium-animate/gallery/story/lecture.json +23 -90
  16. package/skills/presmium-animate/gallery/structure/lecture.json +104 -65
  17. package/skills/presmium-animate/gallery/text/lecture.json +115 -63
  18. package/skills/presmium-animate/gallery/timeline/lecture.json +106 -187
  19. package/skills/presmium-animate/gallery/timeline/scenes/bubble.ts +1 -1
  20. package/skills/presmium-animate/gallery/transitions/lecture.json +103 -52
  21. package/skills/presmium-animate/references/lengths.md +1 -1
  22. package/skills/presmium-animate/references/libraries.md +12 -6
  23. package/skills/presmium-animate/references/procedural.md +1 -0
  24. package/skills/presmium-animate/references/story.md +21 -7
  25. package/skills/presmium-animate/references/team.md +176 -0
  26. package/skills/presmium-author/SKILL.md +53 -19
  27. package/skills/presmium-author/references/assistance.md +3 -1
  28. package/skills/{presmium-present → presmium-author}/references/classroom.md +2 -2
  29. package/skills/presmium-author/references/document.md +1 -1
  30. package/skills/{presmium-present → presmium-author}/references/lecture.md +3 -1
  31. package/skills/presmium-author/references/publishing.md +161 -13
  32. package/skills/presmium-author/references/writing.md +170 -7
  33. package/src/cli.ts +4 -4
  34. package/src/install.ts +42 -5
  35. package/src/messages.ts +5 -5
  36. package/src/resources.ts +5 -4
  37. package/skills/presmium-present/SKILL.md +0 -35
  38. package/skills/presmium-present/references/delivery.md +0 -122
@@ -1,6 +1,6 @@
1
1
  # From thesis to storyboard
2
2
 
3
- How to decide what an animation says before deciding how it moves: the sentence it proves, the picture that proves it, the order of the beats, the narration over them and the review that shows whether a stranger got it. `lengths.md` (this folder) covers the motion itself and what each second of a 1- to 60-second piece shows; `scenarios.md` covers which picture suits which teaching topic; `storyboards.md` holds 34 filled-in storyboards for popular science, papers, courses, data stories and products; `procedural.md` covers motion computed from mathematics (inverse kinematics, physics, curves, fields) and how to keep it seekable. The worked example is the gallery document `gallery/story/lecture.json`: a narrated two-minute flow-matching explainer whose steps are its storyboard and whose numbers come from a real training run.
3
+ How to decide what an animation says before deciding how it moves: the sentence it proves, the picture that proves it, the order of the beats, the narration over them and the review that shows whether a stranger got it. `lengths.md` (this folder) covers the motion itself and what each second of a 1- to 60-second piece shows; `scenarios.md` covers which picture suits which teaching topic; `storyboards.md` holds 34 filled-in storyboards for popular science, papers, courses, data stories and products; `procedural.md` covers motion computed from mathematics (inverse kinematics, physics, curves, fields) and how to keep it seekable; `team.md` covers making one piece with several agents (the storyboard they share, file ownership, concurrent edits, review rounds and the cold-read prompt). The worked example is the gallery document `gallery/story/lecture.json`: a narrated two-minute flow-matching explainer whose steps are its storyboard and whose numbers come from a real training run.
4
4
 
5
5
  ## The process
6
6
 
@@ -11,7 +11,7 @@ Each stage ends in a check; don't start the next stage before the check passes.
11
11
  | 0. Brief | The kind of piece (below), which decides the defaults; audience and what they already know; what they believe before and should believe after; the form that matters most (web page, slides or video); the length, as a range. Ask only what only the person can answer, one to three questions a round and never the same one twice; state the rest as one line of assumptions (length, aspect, music or voice, each paid item with its free option). Keep the requirements as a table: requirement, evidence, what it affects, recommendation, still to confirm | Before and after fit on one line each |
12
12
  | 1. Thesis | "看完后,观众明白 X,因为他们看到了 Y" (After watching, the viewer understands X because they saw Y), X in 25 汉字 or fewer; the same claim as And–But–Therefore | Someone who has seen nothing restates it; the ABT has exactly one But |
13
13
  | 2. Central picture | Three candidate pictures; keep the one in which X becomes a visible property that changes. Draw the money frame: the one still that proves X | Shown for 3 s to a cold viewer, the money frame alone gets something close to X back. If it needs a caption, keep looking |
14
- | 3. Shape | Three storylines that differ in the idea the picture is made of (one element transforming through everything, one camera move through scale, a chain reaction, a split that becomes one), not three orders of the same cards; one of them bold. Each with its shape, its form (below), its first 2 s, its beats, what carries every boundary and what it rules out, look and sound; never the last piece's look or a gallery film's beats by default. Recommend one. Then for the chosen one: where its turn falls (usually 40–60% in); one spatial convention; one meaning per colour; the misconception to confront and the parts to name first | The person picked a storyline (stop and wait, unless they asked for the file or for no stops); the turn is a change in the picture, not a sentence |
14
+ | 3. Shape | Three storylines that differ in the idea the picture is made of (one element transforming through everything, one camera move through scale, a chain reaction, a split that becomes one), not three orders of the same cards; one of them bold. Each with its shape, its form (below), its first 2 s, its beats, what carries every boundary and what it rules out, look and sound; never the last piece's look or a gallery film's beats by default. Recommend one. Then for the chosen one: where its turn falls (usually 40–60% in); one spatial convention; one meaning per colour; the misconception to confront and the parts to name first; a term table: each concept's one name and the synonyms not to use | The person picked a storyline (stop and wait, unless they asked for the file or for no stops); the turn is a change in the picture, not a sentence |
15
15
  | 4. Storyboard | One row per step: the rest frame (the still), what moves, what the viewer now understands, why | The strip of rest frames at thumbnail size tells the story with no sound |
16
16
  | 5. Script | The narration of each step; when its words come; cues | Read aloud with a timer: each step's narration fits its state, or the state is lengthened on purpose |
17
17
  | 6. Animatic | The scene drawing only each state's rest frame, with cuts between them; the narration attached; build and export | The durations add up to the length; every payoff rests at least 2 s; the person approved the contact sheet of rest frames (stop and wait; a note on one frame changes only that frame) |
@@ -46,9 +46,10 @@ The strongest pieces in the gallery have one picture that is the argument: in th
46
46
  - **The claim becomes a visible property that changes**: a length (a time bar's slices, a whisker), a count (dots in a circle, pips per question), a position (a ball on a curve, an escape layer's height) or an identity (the same objects become the answer).
47
47
  - **Numbers come out of the picture.** A readout is computed from what is drawn (the area left of a line, the RMS of the whiskers, the lines of code on screen) and changes at the instant its cause lands, next to it. A number that can't be produced (10.22999999543 MHz) becomes the picture itself, held. Every number needs an anchor the viewer can feel: a marble, a small town, 1,000 songs.
48
48
  - **Concrete before abstract.** One photon, one door, one request before the law; the formula comes last, as a label on a picture already understood (Sanderson, <https://www.3blue1brown.com/faq/>). Name a part only after the picture has shown it, and introduce at most about one new term a minute: in a study of 650 adults jargon lowered understanding even with definitions on hand (Shulman et al. 2020).
49
+ - **Introduce, name, use.** Every concept enters through motion that shows where it comes from and what it consists of; its keyword lands beside it once the motion is done; only then do labels, numbers and the narration use it. A cold viewer of a 19-page explainer stopped at "F3 = 5" on screen before the facts had been numbered. Mark in the storyboard which concepts each step introduces and by which motion (the worksheet's Introduces column), and check the strip for any label used before its step.
49
50
  - **Two linked views are allowed**, sharing colour and clock, with one marked as the argument: code and its memory diagram, a circuit and its energy staircase, the viewer's wrong model and the right one morphing out of it.
50
51
  - **An analogy shows where it breaks**: say it on the reading page or in a footnote step (Glynn's teaching-with-analogies, step 5). "Greenhouse" glass blocks convection; CO₂ restricts radiation.
51
- - **Real UI for tutorials, metaphor for newcomers.** Learners must find the panel in their own app, so tutorials use the full real screen, dimmed and zoomed, not cropped or redrawn (van der Meij 2000: 25% less training time, 60% better retention). A metaphor for a new category lasts one idea, then hands over to the real thing (Dropbox's "magic pocket" gives way to the real folder by about 30 s).
52
+ - **Real UI for tutorials, metaphor for newcomers.** Learners must find the panel in their own app, so tutorials use the full real screen, dimmed and zoomed, not cropped or redrawn (van der Meij 2000: 25% less training time, 60% better retention). A metaphor for a new category lasts one idea, then hands over to the real thing (Dropbox's "magic pocket" gives way to the real folder by about 30 s). Map a metaphor once, on one page and term by term (the user is the non-player character, the agent under test the player), then use the field's own words; several metaphor systems at once (a game's, a court's, Kubernetes') leave the viewer translating.
52
53
 
53
54
  ## 3. Choose a narrative shape
54
55
 
@@ -62,6 +63,7 @@ The strongest pieces in the gallery have one picture that is the argument: in th
62
63
  | Picture → formal | A proof with a counting or geometric picture | small cases → the picture of one case → the move n → n+1 → doubt (pictures can lie) → the formal step, each term coloured like its region | Visual proof of 1 + 3 + … = n² |
63
64
  | Invariant story | Why an algorithm or protocol is correct | the claim → true at the start → each step re-checks it → an adversary fails → drop the precondition and watch it break | Dijkstra, MIT 6.006 L13 |
64
65
  | Worked → faded → solo | A procedure | subgoal labels → one worked run → the last step left to the learner → a solo exercise | Khan Academy algorithms |
66
+ | Method before steps | A methodology: how something is built and checked | one person doing the task, on one concrete case → what makes it hard → the model and the one question it must answer → what the method consists of, the rule each part is derived by, how each is checked → the steps on the same case → how the method itself was validated | An agent evaluation that models the user as a state machine (its first version, a row of step cards, was rejected) |
65
67
  | Ladder of abstraction | A parameter controls behaviour | one concrete run → change it, predict → every value at once → back down at the threshold | Bret Victor; Distill, "Why momentum really works" |
66
68
  | Naive → better → clever | Efficiency or design trade-offs | the obvious method with a cost readout → a tweak that changes a constant → the idea → cost curves side by side | CS50's phone book |
67
69
  | Bug story | Debugging, a program's model | the symptom (predict the output) → a wrong hypothesis ruled out → trace the state → the model → fix → verify | Python Tutor aliasing |
@@ -104,6 +106,8 @@ In Presmium a step rests on the final frame of its state, and that frame is also
104
106
  - **One step = one state = one idea**: one or two sentences of narration over 6–15 s in a teaching segment, less in a promo. Mayer and Chandler's lightning lesson in 16 segments of one or two sentences, each ended by a Continue button, is the model: segmenting d = 1.36, naming the parts first d = 1.00 (Mayer and Moreno 2003, <https://www.uky.edu/~gmswan3/575/9_ways_to_reduce_CL.pdf>). On the web and on slides the reader is that button; in the video the hold after a payoff stands in for it.
105
107
  - **Every rest frame makes sense alone**: a 3-second glance tells what it shows (Duarte's glance test; Disney's staging, checked in silhouette). The exception is a prediction step, whose still is an open question with options on purpose; its answer is the next step, and nothing in it gives the answer away (no updated label, no highlighted edge, no output, no blank shaped like the answer).
106
108
  - **Leave rhythm a trace.** Acceleration, a long hold or a montage are invisible in a still, so the rest frame keeps what the motion did: a pip per round, a chart point per round, the ghost of the earlier state, a trail, a time-space diagram. Prefer pictures that lay time out in space; learners scrub back to what vanished (Kim et al. 2014: 23% of interaction peaks).
109
+ - **The whole frame.** A scene is designed for the full 16:9 frame. Captions are an overlay the presenter can switch off, so no band stays empty for them and the content is never shrunk toward the top; where captions would cover something essential, rearrange the layout. An explainer that kept the bottom 18% free had an empty strip on every slide.
110
+ - **Shapes, keywords and numbers; the explanation is spoken.** Set the limits for words on screen before drawing (one explainer: a node label at most 4 汉字, a value at most 14, at most one new line of explanation a step). A page of two columns of three-line cards was rejected: it was paragraphs in boxes.
107
111
  - **The worksheet**, filled top to bottom before code:
108
112
 
109
113
  ```
@@ -113,19 +117,23 @@ C. Picture the central picture; the money frame; each readout and how the pictu
113
117
  the spatial convention; one meaning per colour; the source of every number; a 3-second glance: what a cold viewer said
114
118
  LOOK: every adjective as a number (premium: a material and its values; clean: a 12-column grid, the accent on one word;
115
119
  playful: spring damping 0.45–0.6). BANNED: the default looks this piece avoids, added to after every render
120
+ TERMS: each concept's one name and the synonyms not to use; one word, one meaning (two roles never share a name,
121
+ a colour or an icon); the register: formal words of the audience's field, colloquial only in a character's speech
116
122
  D. Steps | # | State | Start–end | Rest frame | What moves (one thing; cause → effect) | Viewer now understands |
117
- | Viewer does (predict, quiz, run) | Narration | Words come (with / after / cue) | On-screen text (one line at most) |
123
+ | Introduces (each new concept and the motion that brings it in) | Viewer does (predict, quiz, run) | Narration |
124
+ | Words come (with / after / cue) | On-screen text (one line at most) |
118
125
  | Reads (what the eye reads, in order, each with its time window; windows never overlap) | Sound |
119
126
  | Carries into the next (the element that survives the boundary and what it does, or "cut" and why) | Why |
120
127
  E. Checks durations add up; the thumbnail strip reads silent; read-aloud timing; animatic screened; the review results
121
128
  ```
122
129
 
123
- Put the filled worksheet in the piece's reading-view notes, as the gallery does: the next author sees why each beat exists.
130
+ Put the filled worksheet in the piece's reading-view notes, as the gallery does: the next author sees why each beat exists. When several agents make one piece, the worksheet grows into the storyboard file they all work from (`team.md`).
124
131
 
125
132
  ## 5. Write the script
126
133
 
127
- - **Budget by rate.** Plan 3.5 汉字 a second, holds included (English: about 2.5 words). Synthesized Chinese voices speak about 4–4.5 汉字 a second, the rate Chinese newscasters hold at near-full intelligibility (Chan and Lee 2005); measure the chosen voice, since the engine is the workspace's own (Volcengine built in, or any OpenAI-compatible service, `presmium-present`); the flow-matching video this guide studies speaks 4.9, nearly without pause. A step lasts the longest of its state, its narration plus the trailing pause, and its minimum hold, so narration longer than the state stretches the step without asking.
134
+ - **Budget by rate.** Plan 3.5 汉字 a second, holds included (English: about 2.5 words). Synthesized Chinese voices speak about 4–4.5 汉字 a second, the rate Chinese newscasters hold at near-full intelligibility (Chan and Lee 2005); measure the chosen voice, since the engine is the workspace's own (Volcengine built in, or any OpenAI-compatible service, `presmium-author`); the flow-matching video this guide studies speaks 4.9, nearly without pause. A step lasts the longest of its state, its narration plus the trailing pause, and its minimum hold, so narration longer than the state stretches the step without asking.
128
135
  - **Write to the corners of the picture**: say what the picture can't show (cause, size, consequence), never what it shows. "如图所示,红点越来越多" says nothing; "一个病人传三个,三个传九个" says the rule.
136
+ - **Formal words, the audience's words.** The narration, like titles, labels, legends and metric names, uses formal written words from the audience's field and the names of the term table (`presmium-author/references/writing.md`, section 2); only a character's quoted speech keeps colloquial words. In Chinese a person is 用户 or their role, never 它.
129
137
  - **Speak the words; don't print them over moving pictures.** Narration with the picture beats text with it (modality d = 1.17); narration plus the same text on screen is worse than narration alone (redundancy d = 0.69). One or two key words beside the part they name are fine (spatial contiguity); captions are a separate track, not on-screen text.
130
138
  - **Say it while it happens** (temporal contiguity d = 1.30): the narration and its motion share a step. `narrationStart: "with-animation"` (the default) for a mechanism; `"after-animation"` when the picture should land first and the words name it (a result, a surprise); a narration cue on the key word (`point` or `spot` to aim the eye, a pause timed in `production.cueTimings`) when the words lead.
131
139
  - **Questions turn the acts**: "那有没有可能……直的呢?", "还剩最后一个问题". A 1–2 s silence before the turn, and 6–10 s with a spoken "先暂停,写下答案" after a prediction question in a video (the web view's prediction block waits by itself).
@@ -178,7 +186,7 @@ Before showing anyone, review the export yourself. Make the sheets with ffmpeg f
178
186
 
179
187
  Hand the piece over with a delivery note in its reading view: the creative calls made, the storylines not built, what was measured and what was only looked at, the weakest shot, and the warnings kept on purpose.
180
188
 
181
- A cold viewer saying "clear" is not a pass: Muller's clear video raised confidence and taught nothing. A changed prediction and a retold thesis are. A subagent that sees only the exported rest frames, in order, and has to predict each next step and state the thesis is a cheap first cold viewer; then fix the first step where anyone got lost and screen again.
189
+ A cold viewer saying "clear" is not a pass: Muller's clear video raised confidence and taught nothing. A changed prediction and a retold thesis are. A subagent that sees only the exported rest frames, in order, and has to predict each next step and state the thesis is a cheap first cold viewer; then fix the first step where anyone got lost and screen again. `team.md` (section 7) has its prompt, how to prepare the pictures and narration, and a second pass on names and register; in a 19-page explainer that reader found contradictions, a word with two meanings and drifting names that the makers had not seen.
182
190
 
183
191
  ## The worked example: flow matching
184
192
 
@@ -201,6 +209,12 @@ The example's worksheet is in its reading view. Its data come from `gallery/stor
201
209
  | Anti-pattern | Fix |
202
210
  |---|---|
203
211
  | A topic or a title first ("群体免疫") | The concrete case first, the name after the payoff, if at all |
212
+ | A name, label or number on screen before the picture introduced it ("F3 = 5" before facts are numbered) | Motion first, the name beside it after, then use |
213
+ | Step cards for a method (the generic flow on one side, the example on the other) | What the method consists of, the rule each part is derived by and how it is checked; then the steps |
214
+ | One thing with several names; one name for two roles | The term table; sweep the narration and the scenes' words for its banned synonyms |
215
+ | Colloquial titles, labels and metric names (结论对不对, 拉不开) | Formal words of the audience's field (结论正确性, 无区分度) |
216
+ | A band kept empty for captions | The whole frame; captions are an overlay that can be off |
217
+ | Two columns of three-line cards | Shapes, keywords and numbers; the sentences go into the narration |
204
218
  | A list of facts (and, and, and) | Find the But |
205
219
  | Narration describing what is visible | Cause, size, consequence |
206
220
  | The narration printed over the motion | Speak it; one key word beside its part |
@@ -0,0 +1,176 @@
1
+ # Making one piece with several agents
2
+
3
+ A long explainer (many pages, a hundred steps) can be made by a coordinator and several agents working in parallel, one or a few pages each. This reference comes from a 19-page teaching explainer of about 110 steps, made by nine agents and reviewed in two rounds. Its first version was split well, but without shared names or rules for the register: most of the second round went into making nine agents' words agree, and a cold viewer ranked the drifting names as the top obstacle. The storyboard outline below puts those rules into the first version.
4
+
5
+ The coordinator writes the storyboard and the shared modules, dispatches the pages, settles inconsistencies between pages and runs the reviews. Each agent makes, checks and reports on its own pages. The author decides the claim and anything about the subject itself.
6
+
7
+ ## 1. The storyboard comes first
8
+
9
+ One file at the project's root, `storyboard.md`, that every agent reads before it starts and again whenever it changes. Write sections A to G before any page is assigned; section H grows after each review (section 6). [Story](story.md) is the process behind the brief, the claim, the picture and the step tables; this is what the file must hold so that many agents make one piece.
10
+
11
+ **A. Brief.** The kind of piece; the audience and what they already know; what they understand before and after, as a numbered list the piece has to deliver; the author's requirements, verbatim and numbered, so agents can cite them. For a method, the opening order: one concrete case of a person doing the task, what makes it hard, the model and the one question it must answer, then the method (`presmium-author/references/writing.md`, section 2).
12
+
13
+ **B. Claim.** The thesis sentence and its ABT; the question the whole piece answers and the pages that answer each part of it. The narration of each of those pages points back to the question once.
14
+
15
+ **C. The central picture and the example.** One picture for the whole piece, at the same place and drawn the same way on every page that shows it, by a shared module (section 2): what each element is, how it changes, where each part sits, and where a part may be enlarged and returned to its place (the same object, never a copy faded in). One running example, all its data in that module: the fixed texts (a ticket, a quote) and every number. No agent invents data; a page that needs something the module lacks defines it in its own scene and labels it 示意 (illustrative).
16
+
17
+ **D. Names, colours and space.**
18
+
19
+ - **The term table**: every concept, its one name, the synonyms and calques not to use, the page and step that introduce it, and the sentence that defines it there (`presmium-author/references/writing.md`, section 2). A term appears nowhere before that step, and a page title's terms are defined in the page's first step. Two roles that could be confused (the agent drafting the material and the agent under test) get two names, two colours and two icons.
20
+ - **The register**: titles, labels, legends, metric names and narration in the formal written words of the audience's field, its own terms rather than calques (对照组, not 臂, for an experiment's arm); only a character's quoted speech in a bubble keeps colloquial words. A metaphor system (a game, a court) is mapped term by term on one page; the other pages use the field's own words.
21
+ - **Colours**: one colour, one meaning, as a table of roles (truth, wrong, the user, the agent under test) each mapped to a design token in the shared kit, through `color(name)` or `var(--pm-color-<name>)`, never a raw hex.
22
+ - **Space**: one convention, such as left for upstream, input and before, right for downstream, output and after.
23
+
24
+ **E. Common rules**, short and numbered so reports can cite them:
25
+
26
+ 1. Read first: this skill's `SKILL.md`, `lengths.md`, `story.md` (sections 4–6) and `libraries.md`; `presmium-author/references/writing.md`; one or two gallery pieces close to the page.
27
+ 2. One idea per step; its rest frame reads alone in 3 seconds.
28
+ 3. One thing moves at a time, the cause before the effect; an object that changes place or form moves or morphs, never fades out for a copy.
29
+ 4. On screen only shapes, labels, keywords and numbers, with limits in characters (the explainer: a node label at most 4 汉字, a value at most 14, at most one new line of explanation a step). No narration sentence printed on screen.
30
+ 5. Introduce, then name, then use: a concept first appears through motion that shows where it comes from and what it consists of; its name lands beside it after the motion; only then do labels, numbers and narration use it.
31
+ 6. The method before its steps: what the method consists of, the rule each part is derived by and how it is checked, then the steps.
32
+ 7. The names and register of D, in every label and every line of narration.
33
+ 8. Narration: one or two short paragraphs a step, about 80 汉字 at most, saying what the picture can't show.
34
+ 9. Durations: a step usually 3.5–6 s; a move the eye must follow 600–900 ms, an entrance 300–450 ms, a line drawn 400–600 ms; a result holds 1.5–2 s.
35
+ 10. Any step in any order: the picture is a function of the step and the time only ([Libraries](libraries.md)).
36
+ 11. The whole 16:9 frame is used; captions are an overlay that can be off, so no band is kept for them.
37
+ 12. Colours only from D, type sizes only from the kit's scale.
38
+ 13. The pitfalls in [Libraries](libraries.md), and every new one the coordinator forwards.
39
+ 14. Information: no sentence that defends against a reading nobody would make, no position set up only to be rejected, no list of what the piece does not show (`presmium-author/references/writing.md`, section 2). A negation stays when it states an advantage, a condition, or a position someone holds, named.
40
+ 15. A term's first mention defines it, with D's sentence; on a `scrolly` page that is in the narration.
41
+
42
+ **F. Files and workflow**: who owns which file (section 2), how the document is changed (section 3), the checks, the captures and the report (section 4).
43
+
44
+ **G. Pages.** The page order, grouped into parts, with a page that maps out the parts before the first one. Per page: its key (also the scene file's name), a title that states the page's claim (with a length limit), the earlier claims it rests on, the concepts it introduces with their definitions from D, and a step table:
45
+
46
+ | Step | Rest frame and motion | Introduces (each new concept, and the motion that brings it in) | Narration points |
47
+ |---|---|---|---|
48
+
49
+ The owner designs the drawing and the motion, not what each step says or the order: a step may be split into two, never merged with another or moved.
50
+
51
+ **H. Conventions after review**, appended by the coordinator (section 6).
52
+
53
+ ## 2. Shared modules and ownership
54
+
55
+ Pages read as one piece because they draw the same central picture, and that holds only when it is the same code. Before dispatching, the coordinator writes:
56
+
57
+ - `scenes/kit.ts`: the frame (16:9, sized in `cqw` and `cqh`, its CSS scoped to the scene), the type scale, the colour roles of D mapped to design tokens, and small helpers used everywhere (a chip naming a role in its colour);
58
+ - `scenes/<picture>.ts`: the central picture's geometry, functions that draw it whole or in parts, selector functions for animating its parts, coordinate functions (the centre of a slot, the edge of a node), and the example data of C.
59
+
60
+ Scenes import them with relative `.ts` imports ([Libraries](libraries.md), Rules for every library, shared modules). Ownership is by file:
61
+
62
+ - Each agent writes only its own `scenes/<key>.ts` and its own pages of the document. A helper it needs goes into its own scene file; a bug it finds in a shared module goes into its report.
63
+ - Only the coordinator changes shared modules. A change reaches every page that imports it: tell every agent what changed, and keep the old exports working until the pages have moved. When the explainer's board was enlarged to fill the frame, the pages that had computed slot positions themselves had to be redone; the pages that used the shared coordinate function moved with it.
64
+ - Every word a scene puts on screen sits in one object at the top of its file: renaming a term is one edit there, and the term sweep (section 6) reads one place per scene.
65
+
66
+ ## 3. One document, many writers
67
+
68
+ There is one `lecture.json`, so writers must not overwrite each other.
69
+
70
+ - **One service.** Before dispatching, start `presmium studio` (or `presmium serve`) for the project; `presmium dev` won't do, since it offers neither author actions nor pictures. Every agent connects through the MCP server `presmium mcp`, which relays to that service. Agents never start, stop or restart it and don't run `presmium dev` or builds; the service compiles again when files change, so everyone sees everyone's current pages. Each write may wait for the author's approval in Presmium; whether a run of many agents may write without asking (`presmium serve --allow operate`) is the author's decision, not the agents'.
71
+ - **Author actions are transactions.** A page is created with `plan_page_change` and `apply_page_change`; its blocks, steps, narration and the definition of its scene with `plan_document_change` and `apply_document_change`, which can carry the page's scene file in the same change so that the definition and its code land together. A plan names the source version it was read from. When another agent saved in between, the apply returns 409: read again with `read_document_part`, plan again on the new version and apply that, never the old plan. Changes kept to one page at a time rarely collide.
72
+ - **Without the MCP server**, each page has its own description file (title, scene, static fallback, steps with their narration and duration) owned by its agent, and one script assembles them into `lecture.json` in the storyboard's page order: it writes a temporary file and renames it over the document, so no reader sees half a document, and it derives every ID from the page key and the step index, so assembling again keeps comments and steps attached. Anyone may run it at any time.
73
+
74
+ ## 4. Each agent's loop
75
+
76
+ An agent goes through these after every change, on its own pages only:
77
+
78
+ 1. **Check the document.** `check_document`, then `get_diagnostics`; fix the problems on these pages. A scene whose code doesn't bundle (a syntax error, a missing module) is reported by `check_document` and `presmium check` as a `presmium.preview.code` error with its file and line; it fails alone, so the other pages still preview and present, and its own page shows the failure (the capture's `problems` say why). Fix it before anything else.
79
+ 2. **Reread the words.** Read your pages' narration, titles and on-screen words in order, as someone who has seen only the pages before them, against the storyboard: is each term's first mention its definition from D, and does no term appear before that step? Does any sentence defend against a reading nobody would make, set up a position nobody holds, or list what the piece does not show (E.14)? Is any word a banned synonym or a calque? Does each step's claim follow from what earlier pages stated, without contradicting them? Rewrite what fails; a sentence kept on purpose goes in the report with its reason. This is a reading, not a search: a marker word found by searching is only a candidate, and the sentence in its place decides.
80
+ 3. **Look at every step.** `capture_slides` on each page returns every step's rest frame (12 pictures a call; name `steps` for a longer page). Each must read in 3 seconds, with nothing overlapping or cut off; `measure` with a CSS selector gives the boxes of elements when an overlap is hard to see. Capture again with `arrive: 'backward'` and compare: going back must show the same frame. When the reading page matters, `capture_reading` at 1280 and 390. Change and capture again until every frame passes.
81
+ 4. **Check the motion.** Rest frames don't show it. Capture `at` moments inside the steps where something moves, and read the timeline: every move has a reason that means something (a cause, the same object, things converging); delete the moves that have none.
82
+ 5. **Report** in this form: for each page, its number of steps and one line describing each rest frame; the picture files; the check result; the sentences kept after rereading the words, with their reasons; problems found in shared modules; where the page departs from the storyboard and why; what isn't done or isn't good enough.
83
+
84
+ ## 5. The coordinator during production
85
+
86
+ - Dispatch each agent with the storyboard's path, its pages and files, and the reading list of E.1.
87
+ - Read every report and look at its pictures. Settle a difference between pages (one part drawn two ways, one thing named two ways) at once: decide, write it into the storyboard, tell the agents concerned.
88
+ - Forward a pitfall one agent hit to every agent still working, at once; finding it nine times costs more.
89
+ - After each batch of reports, read the narration of the whole document in order for terms that one page uses before another page defines them: such a term belongs to neither agent alone. Settle it in the term table and tell both.
90
+ - When every page is done, run the cold read (section 7) before the author sees the piece.
91
+
92
+ ## 6. Review rounds
93
+
94
+ Each review, the cold read and then the author's, ends in a new section at the end of the storyboard (H1, H2, …) that says it takes precedence over everything above it. Then send every agent concerned the list of fixes for its own pages. Fixes go back to the agents that made the pages, which still have their context; a new page goes to a new agent with its step table. When a round reverses an earlier convention, edit the earlier entry to point at the new one: in the explainer one round said 观察, not 现象, a later term table mapped 观察 to 现象, and agents had to guess which held.
95
+
96
+ Decisions about the subject itself (a rule of the method, what counts as a cost) belong to the author: ask, don't settle them in a convention.
97
+
98
+ Before the author sees a round, sweep for terms: search the narration and text in `lecture.json` and the on-screen words in `scenes/*.ts` for every banned synonym and calque in the term table, and for the colloquial words the register rules out. A hit is renamed, not explained. Whether a first mention defines its term, whether a sentence carries information and whether the argument holds are judged by reading, in the cold read's third pass (section 7), not by a search.
99
+
100
+ What the explainer's two rounds had to add, usable as a checklist for the first version:
101
+
102
+ - **The picture**: the whole frame used; shared coordinate functions instead of computed positions; no text in a thumbnail too small to read (below about 12 px): enlarge it or keep only the outline.
103
+ - **Roles, colours and names**: confusable roles separated by name and colour; the colour table; a fixed text (the ticket) and the metric names taken from the shared constants; near-synonyms settled.
104
+ - **Facts stated one way everywhere**: each contradiction the cold read found, decided into one statement (what the agent under test can see, what the state holds, why a wrong conclusion can pass, where a language model takes part). A property that holds by design but hasn't been measured is said to be so.
105
+ - **One drawing per recurring part**: a gate that had been drawn three different ways became one barrier: closed dark, open green, refusing red with a shake.
106
+ - **The author's decisions**, the term table (before → after) and the table of page titles.
107
+ - **Rules decided in discussion**, written as content the pages must show, with a step table for any new page.
108
+
109
+ The lessons: the term table and the register belong in the first version (D), and "introduce, then name, then use" belongs in every step table, as its own column.
110
+
111
+ A second explainer (24 pages, eight agents) added three rules in the middle of production, each at the cost of a message to every agent and a rewrite of finished pages: the information rule (E.14), definitions at first mention (D, E.15) and calques in the term table. Its review also had to read the argument as a chain (section 7, third pass): a background page said random reading cannot tell how much was missed, while the method's own bound on the misses came from uniform reading. These are in the outline above, so a first version starts with them.
112
+
113
+ ## 7. The cold read
114
+
115
+ A fresh agent that took no part sees only the pictures and the narration, in order, and reports what a first-time viewer gets. It finds what the makers can't see: contradictions between pages, one word with two meanings, names that drift, concepts used before they were introduced or never defined, sentences that carry nothing, elements nobody explained. In the explainer it found three problems that blocked the main line, more than twenty concepts left unclear and a dozen flaws in pictures, most of which the agents' own page-by-page checks had missed.
116
+
117
+ **When**: after every round of production or fixes, before the author reviews. A new reviewer each round: one that saw the last version already knows the answers.
118
+
119
+ **Prepare the material:**
120
+
121
+ 1. `capture_overview` with `steps: 'all'`, `captions: false` and `images: false` takes every step of every page at rest, the whole slide without the captions over it, into one directory of the service's state, named so that sorted names are the playing order: `03-12-game.png` is page 3, step 12 (pages from 1, steps from 0, as the tools count them). Copy the directory at once: the service keeps only its latest captures. Without `steps: 'all'` it takes each page's last step, and its sheets of thumbnails show the whole piece at a glance.
122
+ 2. A frame taken mid-motion gets reported as a flaw: these are rest frames, drawn from the step alone. Numbers in names must be zero-padded (the tool does it): with `15-1.png` and `15-10.png`, step 10 sorts right after step 1.
123
+ 3. The same directory has `narration.md`, each picture's narration under its file name: the reader looks at whole slides and reads the script as text, instead of small captions over the picture.
124
+ 4. Give nothing else: no source, storyboard, term table or notes, or the reader is no longer cold.
125
+
126
+ **First pass: understanding.** Replace the angle brackets; write the prompt in the document's language when the report should be in it.
127
+
128
+ ```
129
+ You are seeing this explainer for the first time, as a viewer and a reviewer. You are <the audience, e.g. a researcher who evaluates LLM agents and knows incident troubleshooting, but hasn't seen this design>. You took no part in making it. Don't read any source code, storyboard or notes; use only the material below.
130
+
131
+ Material: <N> PNG pictures in <folder>, the rest frame of each step of the presentation. File names are <page number>-<step number>-<page key>.png (steps from 0), and their sorted order is the playing order. <folder>/narration.md has each picture's narration under its file name: read it with the picture, as a viewer hears it. Look at every picture in order with the Read tool; skip none.
132
+
133
+ First, page by page. After each page (all pictures with the same page number), write:
134
+ - what the page says, in one sentence of your own;
135
+ - every concept, shape or label that first appears here and that you don't understand, or that is used before it was introduced (the step, and where in the picture);
136
+ - problems in the pictures: overlapping text or text too small to read, elements whose meaning is unclear, a colour whose meaning changes, a contradiction with the narration (the step, and where);
137
+ - before you look at the next page, predict what it will say; after it, note whether you were right.
138
+
139
+ At the end:
140
+ - the claim of the whole piece in your own words, in three to five sentences: the problem, the method, why the method solves it;
141
+ - the steps of <the core process, e.g. how one task becomes a state machine>;
142
+ - what you still don't understand;
143
+ - the problems to fix, the most serious first: P0 (blocks the main line), P1 (leaves one concept unclear), P2 (a flaw in a picture). Write each as "file · where · problem → suggested change".
144
+
145
+ Change no files. Be specific; don't praise what works.
146
+ ```
147
+
148
+ **Second pass: names and register**, sent to the same reviewer once the first report is in, because wording is a cost of understanding too:
149
+
150
+ ```
151
+ Check the wording once more, still changing no files:
152
+ 1. Names: which things are called by several names on different pages? Which word means different things on different pages? List each, with where.
153
+ 2. Field terms: which words would <the audience's field, e.g. an operations engineer> not use day to day? Are several metaphor systems mixed (a game's, a court's, Kubernetes')? Give a table that replaces them with the field's everyday words.
154
+ 3. Register: which titles, labels, legends, metric names and lines of narration are colloquial? Give a table of formal replacements. A character's quoted speech in a bubble may stay colloquial; leave it out.
155
+ 4. In Chinese narration, is a person referred to as 它?
156
+ Add these to the problem list as P0, P1 or P2.
157
+ ```
158
+
159
+ **Third pass: definitions, information and the argument**, sent to the same reviewer after the second:
160
+
161
+ ```
162
+ One more pass, still changing no files:
163
+ 1. The argument: write each page's claim in one sentence and the earlier pages it rests on. Where does a later page contradict, or quietly drop, what an earlier page stated? Where is a claim made without the step, picture or number that supports it?
164
+ 2. Definitions: for each term, the first picture where it appears. Does that step's narration say what it is? List the terms used before they were defined and those never defined.
165
+ 3. Sentences that carry nothing: which sentences defend against a reading nobody would make (does not mean, only shows, cannot tell), set up a position nobody holds in order to reject it, or list what the piece does not show? For each, say whether to delete it or to narrow the earlier claim instead.
166
+ 4. Calques: which terms are word-for-word translations that people in <the audience's field> would not say? Give the field's own word.
167
+ Add these to the problem list; a contradiction in the argument is a P0.
168
+ ```
169
+
170
+ **Use the report:**
171
+
172
+ 1. A P0 is usually a contradiction or a role ambiguity: decide one statement for the whole piece, write it into the storyboard (H) and send it to the pages concerned. A contradiction in the argument is corrected where the wrong statement is made, usually the earlier page.
173
+ 2. A problem with the method itself, such as a rule whose reason no longer holds, goes to the author; don't decide it.
174
+ 3. The wording problems become one term table in the storyboard, which every page follows; definitions and calques go into its columns, which the next round's agents and reviewer read against.
175
+ 4. Fixes go to the agents that made the pages.
176
+ 5. After the fixes, capture everything again and give it to a new reviewer.
@@ -1,46 +1,80 @@
1
1
  ---
2
2
  name: presmium-author
3
- description: "Create and edit a Presmium teaching document: the sole authoritative lecture.json, stable pages and rich-text blocks, steps, narration, assets and component definitions; validate, preview and publish it. 写讲义、改文稿、安排页面、正文、分步与讲稿、检查和构建时使用。"
3
+ description: "Write, edit, present and produce a Presmium teaching document: the sole lecture.json with its pages, blocks, steps and narration; its reading version (web page, notebook) and presentation version (slides, narrated lecture video); writing style for both; voiceover, captions, classroom, export and publishing. Use it to write or revise a lecture, plan pages, write slide text or narration, check, preview, present, record, generate voiceover or export. 写讲义、改文稿、写正文与幻灯片文字、写讲稿、配音、字幕、放映、上课、导出、发布时使用。"
4
4
  ---
5
5
 
6
6
  # Authoring a Presmium document
7
7
 
8
- A **document** is a folder containing `lecture.json`. This normalized, editable teaching document IR is the only content authority. The compiler derives a runtime snapshot for reading, slides, notebooks and narrated playback. Do not create `lecture.md`, `slides.md`, Markdown mirrors or a second BlockNote document file. Ordinary Markdown READMEs and code files remain ordinary project files.
8
+ A **document** is a folder containing `lecture.json`: the only editable source of a teaching document. Everything readers see is derived from it by the compiler: the **reading version** (the web page, and a notebook when listed) and the **presentation version** (the slides, and the narrated **lecture** video made from the slides and the narration). Don't create `lecture.md`, `slides.md` or any second copy of the content.
9
9
 
10
- A **workspace** has `presmium.workspace.yaml`; its `documents` patterns name JSON entries, normally `*/lecture.json`. A **lecture** means narrated playback, not the editable document. The studio is the browser editor started by `presmium studio` or `presmium-studio` when installed.
10
+ A **workspace** has `presmium.workspace.yaml`; its `documents` patterns name the documents, normally `*/lecture.json`. The **studio** is the browser editor started by `presmium studio`.
11
+
12
+ Terms used throughout:
13
+
14
+ | Term | Meaning |
15
+ |---|---|
16
+ | Page | A section of the document; pages are ordered by `sectionOrder` |
17
+ | Block | One piece of content on a page: `text`, `image`, `code`, `component` (an animation or interactive part) or `container` |
18
+ | Step | One state of a page: which blocks are visible, which state each component shows, which narration is spoken. Slides advance step by step |
19
+ | Narration | The spoken script of a step: heard in the lecture video, shown to the presenter, never on the reading page |
20
+ | Form | What the document is built into, by renderer id: `web` (reading page), `notebook`, `slides` (presentation), `lecture` (narrated video from the slides). `metadata.renderers` lists the forms a document builds; a new document lists all four |
21
+ | Presenter View | The presenter's window while presenting slides: current and next slide, the narration as notes |
11
22
 
12
23
  ## Choose the work
13
24
 
14
- | Author's task | Read |
25
+ | The author asks to | Read |
15
26
  |---|---|
16
- | Write, organize or revise content | [Writing](references/writing.md), [Document format](references/document.md) |
27
+ | Write a lecture, revise text, plan pages, write slide text or narration | [Writing](references/writing.md) first, then [Document format](references/document.md) |
17
28
  | Show code, reference project files or run code | [Code](references/code.md) |
18
29
  | Show something moving or explain a process | `presmium-animate` |
19
- | Narration, voices, subtitles, recording or video | `presmium-present/references/lecture.md` |
20
- | Build a site, a translation or student output | [Publishing](references/publishing.md) |
21
- | Use the studio or ask an agent to change a document | [Assistance](references/assistance.md) |
30
+ | Make one large piece with several agents in parallel | `presmium-animate/references/team.md` |
31
+ | Generate voiceover, choose voices, set captions, record or make the video | [Lecture production](references/lecture.md) |
32
+ | Build a site, slides, PDF, PowerPoint, notebook, translation or student version; prepare offline | [Publishing](references/publishing.md) |
33
+ | Write or restyle a site's homepage (`site/home.json`), choose its theme | [Publishing, Write the homepage](references/publishing.md#write-the-homepage) |
34
+ | Run a class with quizzes, polls and students following along | [Classroom](references/classroom.md) |
35
+ | Details of every studio and MCP action: conflicts, approvals, audio and image import, transcription | [Assistance](references/assistance.md) |
22
36
  | Implement a component or service | `presmium-develop` |
23
37
 
24
- ## Read and change the authority
38
+ ## Writing in one paragraph
39
+
40
+ Each page has one idea and two versions. The reading version is written like a book: formal written language, Chinese in Chinese word order and English in English word order, every sentence carrying information. The presentation version shows a claim as its heading, keywords and pictures, and moves with steps; its explanation is the narration, a separate spoken script rather than the reading text read aloud. Both use one name per concept throughout, and formal words of the audience's field (its own terms, not calques) in titles, labels and narration; a concept is shown before it is named and used, and its first mention defines it. Neither version defends against a reading nobody would make. Shared figures, animations and code are written once; reading paragraphs are limited to `["web", "notebook"]` (or `["web"]` when the document doesn't build a notebook), slide keywords to `["slides", "lecture"]`. [Writing](references/writing.md) has the rules and the review.
41
+
42
+ ## Work through the tools
43
+
44
+ When the MCP server `presmium` offers author actions (the studio's assistant; or `presmium mcp` while Presmium Studio or `presmium serve` runs for the project, which a new project's `.mcp.json` connects Claude Code to), change the document through them, the same actions the studio's buttons use. The server's instructions list this order too; each tool describes its own parameters.
25
45
 
26
- 1. Read `lecture.json`, workspace configuration and the referenced code/assets relevant to the request. Keep existing IDs when changing or moving an object.
27
- 2. Work with the domain entities: `sectionOrder` and `sections`, `blocks`, `steps`, `narrations`, `assets`, `definitions`, `production`. Entity map keys equal their `id` values. Page and child ordering are ID arrays.
28
- 3. Text is typed rich text with stable paragraph/list/table identities. Do not serialize it to Markdown for editing. Content has one parent; reuse a definition or asset instead of assigning one block to two parents.
29
- 4. Each section has at least one step. A step names visible block states and narration IDs. Component state IDs come from the definition's public states, never guessed numeric positions. Timing belongs only in `production`.
30
- 5. Keep unknown versioned component data intact. Report unsupported capability; never delete data to make a view look editable.
31
- 6. Validate with `presmium check <document>` and build only the form relevant to the request. In the studio, saving the document must succeed independently of snapshot compilation. A previous successful snapshot may be stale; check its document version.
46
+ 1. **Find the target.** `list_documents`; `get_focus` gives what the author has selected or pointed at, so "this page" or "this paragraph" means that.
47
+ 2. **Read before writing.** `get_authoring_capabilities`, then `get_document_outline` for the pages and entities, then `read_document_part` for the complete values you will change. Read the surrounding pages too: a change must fit the document's claim and terms.
48
+ 3. **Plan, then apply.** Page create, rename, move and delete: `plan_page_change`, `apply_page_change`. Content, steps and narration: `plan_document_change`, `apply_document_change`. Pass the source version you read; a 409 means the document changed, so read again and plan again rather than retrying. A write may wait for the author's approval in Presmium; a refusal is final for that request. `approval-unavailable` means no Presmium window is open to ask: tell the author to open Presmium Studio (or to start `presmium serve --allow operate`).
49
+ 4. **Check.** `check_document`, then `get_diagnostics` for the full list. Fix what you caused; report what you can't fix in words the author understands.
50
+ 5. **Look at the result.** `capture_slides` returns pictures of a changed page as the presentation shows it: the rest frame of every step, or with `at` moments (milliseconds) into a step's animation, and with `measure` (a CSS selector) the boxes of its elements in slide pixels; `capture_reading` returns the same page in the reading version at a window `width` (390 for a phone); `capture_overview` takes every page at once, for reviewing the whole document. Look at them for overflow, overlaps, what each step shows, the phone layout and the dark appearance before you report; a successful compile doesn't prove the page reads well or that its steps work. Don't script a browser for this.
51
+ 6. **Voiceover and outputs are explicit.** Editing narration never generates audio. Read `get_voiceover_status`, tell the author the engine, the voice and the number of sentences (a cloud engine charges for them), and call `start_voiceover` only after the author agrees. `build` and `get_builds` make and list outputs. Details in [Lecture production](references/lecture.md) and [Publishing](references/publishing.md).
32
52
 
33
- ## Commands
53
+ Undo is `undo_document_change`; `get_document_history` lists the saved changes.
34
54
 
35
- The default document starts with one empty page named from the supplied title.
55
+ To connect an AI tool: a project made by `presmium new` has `.mcp.json` for Claude Code; otherwise run `claude mcp add presmium -- presmium mcp` or `codex mcp add presmium -- presmium mcp` in the project. `presmium mcp` relays to the Presmium Studio or `presmium serve` running for the project and follows it when it starts again (a `presmium dev` only previews: it has no author actions and takes no pictures); with neither running it only reads, checks and exports, and the author starts `presmium studio` then reconnects the server.
56
+
57
+ Without an MCP host that has author actions (working on files in a project), edit `lecture.json` directly and use the command line:
36
58
 
37
59
  ```sh
38
60
  presmium new lesson --type lecture --title 'Lesson'
39
- presmium dev lesson
40
61
  presmium check lesson --json
62
+ presmium dev lesson
41
63
  presmium build lesson --to web
64
+ presmium build lesson --to slides
42
65
  presmium ir lesson --out runtime-snapshot.json
43
66
  presmium studio .
44
67
  ```
45
68
 
46
- Commands use `pnpm` and `presmium`; install the project dependencies with `pnpm install`. Never hand-edit `dist/` or derived runtime snapshot fields such as numeric `at`, `span`, step maps, published URLs or playback start times. The one-time repository migration is not an authoring or compatibility mode.
69
+ Commands use `pnpm` and `presmium`; `pnpm add -g @lincyaw/presmium` includes Studio, renderers and official plugins. The global command uses its installed version; use `pnpm exec presmium` to choose the project version. Install project dependencies with `pnpm install`. Generating voiceover has no command of its own: it runs in the studio (Video Production) or through `start_voiceover` on an MCP host, which `presmium studio` and `presmium serve` provide. With the voiceover generated, `presmium-lecture export lesson` writes the video ([Lecture production](references/lecture.md)).
70
+
71
+ ## Rules for the source
72
+
73
+ 1. Work with the document's entities: `sectionOrder` and `sections` (pages), `blocks`, `steps`, `narrations`, `assets`, `definitions`, `production`. Map keys equal their `id`. Page order and child order are ID arrays.
74
+ 2. Keep IDs when changing or moving anything: comments, steps, narration and translations stay attached through them.
75
+ 3. Text is typed rich text with stable paragraph, list and table IDs, never Markdown in a string. A block has one parent; reuse a definition or an asset instead of giving one block two parents.
76
+ 4. Each page has at least one step. A step names the visible blocks, the component states and the narration IDs; a component's state names are the ones its definition declares, never guessed positions. Timing and voices belong only in `production`.
77
+ 5. Keep unknown versioned component data intact. Report an unsupported capability; never delete data to make a view editable.
78
+ 6. Never hand-edit `dist/` or derived snapshot fields (numeric `at`, `span`, step maps, published URLs, playback times). A failed compile doesn't undo a valid saved edit, and a previous successful preview may be stale: check which version it shows.
79
+ 7. Voices and engines come from the workspace's speech service; never invent a voice catalogue or claim an option works without checking. Operator credentials and endpoints stay outside the document.
80
+ 8. Check the real output: visible text, captions, step navigation and audio. Report what was run and what was not.
@@ -1,11 +1,13 @@
1
1
  # Editing with the studio and an agent
2
2
 
3
- Run `presmium studio <workspace-or-document>` when the Studio package is installed; open the complete address it prints. Editing and preview need no model. The document editor uses one native BlockNote editing surface across the whole document, including cross-block selection and native history/comments.
3
+ Install Presmium once with `pnpm add -g @lincyaw/presmium`; Studio is included. Run `presmium studio <workspace-or-document>`; open the complete address it prints. Editing and preview need no model. The document editor uses one native BlockNote editing surface across the whole document, including cross-block selection and native history/comments.
4
4
 
5
5
  Web and agents modify the same `lecture.json`. Read the current document version, submit semantic edits or a full JSON document using the workspace's document transaction API, and retain unsaved input on conflict. `baseDocumentVersion` is the authoring CAS version, not a runtime IR digest.
6
6
 
7
7
  When connected to a workspace MCP host, read `get_authoring_capabilities`, discover saved entities with `get_document_outline`, then read complete values with `read_document_part`. Retain source on every continuation and use returned offsets to assemble explicit JSON-text fragments before parsing once. A changed source returns 409; restart the read rather than combining versions. The full `get_document` remains available to SDK consumers but may exceed the agent's tool-result budget. Changes use `plan_document_change` and `apply_document_change` through the Web transaction and return saved-source verification; generic large change inputs/results are not yet bounded. Compilation is a separate result. Do not substitute mouse automation or an edited runtime snapshot for an available author action. Compiler-only stdio reports these authoring services unavailable.
8
8
 
9
+ To see a page as the presentation shows it, call `capture_slides` with its section: it returns PNG pictures (and their files in the service's state directory) of every step's rest frame, or of the steps and `at` moments you name (milliseconds into a step's animation, drawn by the same step clock a lecture export uses, so a picture is the same each time it is taken). `measure` adds the boxes of the elements matching a CSS selector, in slide pixels, with their text and `data-*` attributes; `appearance: 'dark'`, `scale: 2` and `clip` cover the dark theme, fine detail and one region; `captions: false` leaves out the captions drawn over the slide, and each frame's narration is in the result as text either way. At most 12 pictures a call. `arrive: 'backward'` reaches each step from the step after it, as a presenter going back does, with the page's own clock: compare it with the direct picture; `capture-page-reloaded` means going back reloaded the page. `capture_overview` takes every page at once (each page's last step, or every step with `steps: 'all'`) into one directory named in reading order, with sheets of labelled thumbnails; it is the material of a cold-read review. `capture_reading` takes one page of the reading version at a window `width` (default 1280, 390 for a phone), scrolled through so that its components load, at rest, cut at 8000 pixels. A scene whose code doesn't bundle fails alone: its page shows the failure, the capture's `problems` say why, and `check_document` (like `presmium check`) reports it as a `presmium.preview.code` error with its file and line. When the whole document can't be prepared the capture fails with `capture-preview-failed`, and `get_diagnostics` holds the reason.
10
+
9
11
  For existing workspace audio, read `get_audio_authoring_capabilities`, then call `inspect_workspace_audio` with the saved source and a permitted same-document workspace-relative path. Pass the returned exact file path, SHA-256 and byte length to `import_workspace_audio`; inspect the resulting saved asset with `inspect_document_audio`. These use the Web media transaction and readback, with agent origin and required-review enforcement. Keep the same change ID when reconciling a lost response; receipts are process-local and only reusable while their result remains current. Import does not create narration or a clip and does not start ASR or TTS.
10
12
 
11
13
  For an existing workspace image, read `get_image_authoring_capabilities` for the current source, then call `inspect_workspace_image` with that source and a same-document workspace-relative path such as `<document>/figure.png`. Pass the returned exact `file` object to `import_workspace_image` with a fresh change ID. It uses the Web image transaction, records agent origin and refuses when review is required; a stale source returns 409 and a changed file returns `image-file-changed`, both before the author is asked to approve. When the author denies the request or it times out, the tool returns `operation-not-allowed` (403, not retryable): do not retry it on your own; ask the author. Import only registers the asset: to show it, insert an `image` block with its `assetId` and an `alt` text through `plan_document_change` and `apply_document_change`.
@@ -38,9 +38,9 @@ Do not run a class from `presmium dev` or `presmium serve`. Their built-in class
38
38
  presmium build --to web --out dist-full
39
39
  ```
40
40
 
41
- `--audience student` leaves out content marked for teachers only (for example a block with `audience: ["teacher"]`; the markers are explained in `presmium-author/references/publishing.md`, "Content for students"). The two versions keep students at the same section as the presenter by the sections' ids, so keep stable section IDs when you edit between builds.
41
+ `--audience student` leaves out content marked for teachers only (for example a block with `audience: ["teacher"]`; the markers are explained in [Publishing](publishing.md), "Content for students"). The two versions keep students at the same section as the presenter by the sections' ids, so keep stable section IDs when you edit between builds.
42
42
 
43
- 5. **Serve them** as static sites on the class network (commands in [delivery.md](delivery.md), "Give readers a web address"): `dist-student/web` for students, `dist-full/web` for the teacher.
43
+ 5. **Serve them** as static sites on the class network (commands in [Publishing](publishing.md), "Give readers a web address"): `dist-student/web` for students, `dist-full/web` for the teacher.
44
44
 
45
45
  **Network and safety.** The classroom server has no TLS and no login: anyone with the join link can join, so run it on the class's own network. A site served over HTTPS needs a `wss://` server address the browsers can reach. Only the browser window that created a classroom can end or archive it, open and close its quizzes, or move its students; everyone else writes only their own answers, questions, votes and submissions.
46
46
 
@@ -4,7 +4,7 @@
4
4
 
5
5
  A document has `schemaVersion`, `id`, `metadata`, `sectionOrder`, `sections`, `blocks`, `steps`, `narrations`, `assets`, `definitions` and `production`. Metadata includes title/language and optional plugins, renderer settings, execution, checks and translations. Credentials belong in operator settings, never metadata.
6
6
 
7
- Sections contain a title, ordered child block IDs, ordered step IDs and a layout (`stack`, `columns`, `canvas` or `scrolly`). Blocks are typed `text`, `container`, `image`, `code` or `component`. Containers own child IDs; component instances reference a definition plus their own parameters; image blocks reference an asset.
7
+ Sections contain a title, ordered child block IDs, ordered step IDs and a layout (`stack`, `columns`, `canvas` or `scrolly`). On the reading page a `scrolly` section keeps its figures in place while a track of its steps scrolls beside them, each step showing its narration, so that narration is read as well as heard ([Writing](writing.md), section 6). Blocks are typed `text`, `container`, `image`, `code` or `component`. Containers own child IDs; component instances reference a definition plus their own parameters; image blocks reference an asset.
8
8
 
9
9
  Text blocks contain structured `paragraph`, `heading`, `list`, `blockquote`, `code`, `math` and `table` nodes. Actual editing units and list/table children retain IDs. Inline content is `text` with marks, `link`, `math` or `break`; rich text is adapted through BlockNote's public API. Do not put Markdown source in a string field to imitate this model.
10
10
 
@@ -1,5 +1,7 @@
1
1
  # Narration, speech and lecture production
2
2
 
3
+ How to write the narration (a spoken script for the presentation, not the reading text read aloud) is in [Writing](writing.md), section 6. This file covers turning it into voiceover, captions and video.
4
+
3
5
  `lecture.json` is the only content authority. Narrations contain typed text, pronunciation and cue nodes; steps name narration IDs. Read the installed kernel contract for exact fields. Captions, spoken text and alignments derive from the same narration structure. A transcript becomes authored text only through an explicit adopt action. Read a Whisper transcript before adopting it: `.en` models translate non-English speech into English; it invents "Thank you." over silence, so drop words that start inside a final silence (`silencedetect=noise=-35dB:d=0.6`); more than 20% `♪` or `�` tokens means it failed; Chinese can come back as one "word" per sentence, sometimes in Traditional characters for Simplified speech, so split it into phrases and spread the time by character count.
4
6
 
5
7
  ## Open the saved version in the studio
@@ -8,7 +10,7 @@ Use the document toolbar's presentation preview action after the authoring save
8
10
 
9
11
  The presentation identifies its confirmed source version. When the source or an observed project dependency changes, use the refresh icon's explicit recompile action to adopt the new result. Unconfirmed runtime revisions are hidden. This version check does not freeze historical project assets or external dependencies.
10
12
 
11
- To embed a lecture in another page of the same site, put its presentation in an iframe: `slides/?view=present&track=<id>&autoplay`, adding `&section=<id>&step=<k>` to start at a step. The player starts once it is ready; browsers allow sound only after a click on the embedding page, so load the iframe from that click. Audio clips are positioned by seeking, so the host must answer byte-range requests (GitHub Pages does).
13
+ To embed a lecture in another page of the same site, put its presentation in an iframe: `slides/?view=present&track=<id>&autoplay`, adding `&section=<id>&step=<k>` to start at a step. The player starts once it is ready; browsers allow sound only after a click on the embedding page, so load the iframe from that click. Where the browser still refuses, the presentation waits at its start with a large Play button. The presentation posts `{ type: 'presmium:state', drawn, section, step, lecture }` to the embedding page (`lecture`: `loading`, `waiting`, `playing`, `paused` or `failed`); `whenPresentationReady` from `@lincyaw/presmium/site` waits for it. Audio clips are positioned by seeking, so the host must answer byte-range requests (GitHub Pages does).
12
14
 
13
15
  Keys while presenting: left/right arrows move a step, Space plays or pauses the lecture (with nothing to play it moves to the next step), O opens the overview, Shift+F goes full screen, Escape ends the show. In Video production, Space plays or pauses and left/right arrows select the previous or next step across pages, also while the preview has the focus. Ctrl+S (⌘S) saves at once anywhere in the studio. Text fields, editors, open menus and dialogs keep their keys; a control reached with Tab keeps Space; after a click on a control, Space and the arrows do the shortcut instead of pressing that control again. Settings → Keyboard Shortcuts lists these keys.
14
16