@lincyaw/skills 1.0.0-rc.15 → 1.0.0-rc.16

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lincyaw/skills",
3
- "version": "1.0.0-rc.15",
3
+ "version": "1.0.0-rc.16",
4
4
  "description": "Presmium's bundled authoring, animation, presentation and plugin-development skills for coding agents",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -36,7 +36,7 @@
36
36
  ],
37
37
  "dependencies": {
38
38
  "jiti": "^2.7.0",
39
- "@lincyaw/kernel": "1.0.0-rc.15"
39
+ "@lincyaw/kernel": "1.0.0-rc.16"
40
40
  },
41
41
  "presmium": {
42
42
  "skills": [
package/skills/index.json CHANGED
@@ -12,8 +12,8 @@
12
12
  "references/publishing.md",
13
13
  "references/writing.md"
14
14
  ],
15
- "version": "1.0.0-rc.15",
16
- "hash": "87be742ce34e397208f807c772ab7f87f21a01140b60ecbf1a4e5bcb56bc4e7e"
15
+ "version": "1.0.0-rc.16",
16
+ "hash": "2df638635135c4ddcf4f1df26d37926037a4fbc9f44ad1f03b4fc5d8dc4728b5"
17
17
  },
18
18
  {
19
19
  "name": "presmium-animate",
@@ -535,10 +535,11 @@
535
535
  "references/scenarios.md",
536
536
  "references/story.md",
537
537
  "references/storyboards.md",
538
+ "references/team.md",
538
539
  "references/timeline.md"
539
540
  ],
540
- "version": "1.0.0-rc.15",
541
- "hash": "6e88b26891f8db23cc9c6e7750ab5468e66fd1813e39e8f63c551c50ea32358c"
541
+ "version": "1.0.0-rc.16",
542
+ "hash": "1cbad1195775bd41f46ec58866bf15bcdbafcef6f660dbe77e1b424f20b52caf"
542
543
  },
543
544
  {
544
545
  "name": "presmium-develop",
@@ -548,7 +549,7 @@
548
549
  "references/plugin.md",
549
550
  "references/testing.md"
550
551
  ],
551
- "version": "1.0.0-rc.15",
552
+ "version": "1.0.0-rc.16",
552
553
  "hash": "9b3cab9683b45f11c631a19f916639ffb4c0f74c054c14baee24aa5655a35de4"
553
554
  }
554
555
  ]
@@ -27,6 +27,8 @@ A teaching segment, an explainer or paper video, a promo, a product demo and a d
27
27
 
28
28
  [Story](references/story.md) is the process, each stage ending in a check: brief, thesis, central picture, three storylines for the person to pick, a storyboard of rest frames with what carries each boundary, the script, an animatic the person approves, motion, review against the spec and with cold viewers. [Storyboards](references/storyboards.md) has filled-in examples for popular science, papers, courses, data stories and products; [Scenarios](references/scenarios.md) the usual pictures for each subject.
29
29
 
30
+ A piece too large for one agent is made from one storyboard file every agent reads, with a term table, shared scene modules that only the coordinator changes, edits through the MCP author actions, review rounds appended to the storyboard and a cold read by a fresh agent: [Team](references/team.md).
31
+
30
32
  ## 5. Motion, rhythm and sound
31
33
 
32
34
  [Lengths](references/lengths.md): what each second shows at 1, 5, 10, 30 and 60 s, the rules every piece follows, the polish list, measured rhythm, carrying beats instead of replacing them, an operated camera, product screens, sound and music, and how to build and export a film.
@@ -41,7 +43,7 @@ Register an explicit component definition in `definitions` with a file implement
41
43
 
42
44
  Narration is structured in `narrations`; steps name narration IDs. Cue targets use stable block IDs. Timing and voice inheritance belong in `production`, never a second timing object on a step or scene. The voice comes from the workspace's speech engine (Volcengine built in, or an OpenAI-compatible service); see `presmium-author/references/lecture.md` for synthesis, playback and export, and `presmium-author/references/writing.md` for how narration is written.
43
45
 
44
- Validate the edited document, then build only the relevant form. Open the actual result, jump forward and backward in arbitrary order, and inspect the static fallback if it matters. Do not claim an animation works merely because JSON validation or compilation succeeded.
46
+ Validate the edited document (`presmium check` or `check_document` also bundles each scene and reports one that doesn't compile, with its file and line), then look at the actual result. With the MCP server, `capture_slides` gives the rest frame of each step of a page and, with `at`, frames that many milliseconds into a step's animation, drawn by the step clock as a lecture export draws them, so they are reproducible; `measure` returns the boxes of elements (a CSS selector) in slide pixels, for positions and overlaps. Capture the steps in any order you like, since each picture is made from its step and time alone; `arrive: 'backward'` checks that going back to a step shows its frame, and `capture_reading` shows the scene on the reading page, also at a phone width (390). Without the MCP server, build only the relevant form, open it, jump forward and backward in arbitrary order, and inspect the static fallback if it matters (exports print it). Do not claim an animation works merely because JSON validation or compilation succeeded, and do not write browser scripts for pictures the tool takes.
45
47
 
46
48
  ```sh
47
49
  presmium check lesson --json
@@ -12,7 +12,8 @@ export default animeScene(({ root, anime, at, color }) => {
12
12
  const [cx, cy] = CENTERS[i % 3]
13
13
  return [cx + gauss() * 120, cy + gauss() * 85] as [number, number]
14
14
  })
15
- const palette = [color('accent'), color('warn'), color('ok')]
15
+ // A cluster is an identity, not a status: the categorical colours, taken in order.
16
+ const palette = [color('category-1'), color('category-2'), color('category-3')]
16
17
  const muted = color('muted')
17
18
  // k-means, run up front: the assignments and centroid positions of each round.
18
19
  let cents: Array<[number, number]> = [[150, 380], [300, 60], [700, 400]]
@@ -33,6 +33,6 @@ export default gsapScene(({ root, gsap, at, color }) => {
33
33
  tl.to(bar(1), { left: slot(2), duration: 0.5 }, s(4))
34
34
  tl.to(bar(5), { left: slot(4), duration: 0.5 }, s(4) + 0.6)
35
35
  tl.to(bar(3), { left: slot(3), duration: 0.5 }, s(4) + 0.6)
36
- tl.to(bar(5), { backgroundColor: '#2e8b57', duration: 0.3 }, s(4) + 1.1)
36
+ tl.to(bar(5), { backgroundColor: color('ok'), duration: 0.3 }, s(4) + 1.1)
37
37
  return tl
38
38
  })
@@ -2,7 +2,7 @@
2
2
 
3
3
  # Choosing a library and writing the moves
4
4
 
5
- Every library here is driven the same way: the scene file builds a timeline (or a drawing function) once, and Presmium pauses it and seeks it to the time it needs. What differs is what each library draws well. The pitfalls below are the ones met while building this skill's gallery (`gallery/<library>/`, see "The gallery" in `SKILL.md`), each checked by seeking the scene forward and back in a browser, in light and dark.
5
+ Every library here is driven the same way: the scene file builds a timeline (or a drawing function) once, and Presmium pauses it and seeks it to the time it needs. What differs is what each library draws well. The pitfalls below are the ones met while building this skill's gallery (`gallery/<library>/`, see "The gallery" in `SKILL.md`) and a 19-page explainer made by several agents, each checked by seeking the scene forward and back in a browser, in light and dark.
6
6
 
7
7
  ## What a scene receives
8
8
 
@@ -22,16 +22,19 @@ Each library counts time in its own unit: GSAP and Motion in seconds (`at(k) / 1
22
22
 
23
23
  ## Rules for every library
24
24
 
25
- - **Colors** come from `color(name)` or `var(--pm-color-<name>)`. Names: `bg`, `surface`, `sunk`, `code`, `ink`, `muted`, `line`, `line-strong`, `accent`, `accent-soft`, `accent-line`, `on-accent`, `ok`, `ok-soft`, `warn`, `warn-soft`, `danger`, `danger-soft`, `syntax-key`, `syntax-string`, `syntax-keyword`, `pointer-fill`, `pointer-stroke`, and for light and shade `sheen` (stays light in both themes) and `shadow` (stays dark). Mix with `color-mix(in oklab, var(--pm-color-accent) 40%, transparent)`.
25
+ - **Colors** come from `color(name)` or `var(--pm-color-<name>)`. Names: `bg`, `surface`, `sunk`, `code`, `ink`, `muted`, `line`, `line-strong`, `accent`, `accent-soft`, `accent-line`, `on-accent`, `ok`, `ok-soft`, `warn`, `warn-soft`, `danger`, `danger-soft`, `syntax-key`, `syntax-string`, `syntax-keyword`, `pointer-fill`, `pointer-stroke`, and for light and shade `sheen` (stays light in both themes) and `shadow` (stays dark). Mix with `color-mix(in oklab, var(--pm-color-accent) 40%, transparent)`. Never type a raw hex or `rgb()` value into a scene or a shared kit: it stays the same in the dark theme and outside the design system. A piece's own colour roles (truth, wrong, the user) are names for design tokens, mapped once in its shared kit. For identities (roles, actors, series, categories) use `category-1` to `category-8`, in order, each with a `-soft` fill: text on a soft fill is `ink` and the category colour draws the edge, and past four categories label them as well; they never mean status, which stays with `ok`, `warn` and `danger`, and `accent` stays the emphasis.
26
26
  - **Light and shade by theme.** The scene is built again when the theme changes, so decide at build from `color('bg')`. A white highlight (sheen, hot core, sparkle) reads as light on the dark page but as a gap on a white card: on the light page use the accent mixed with `shadow` instead. A halo in the accent color muddies the light page and reads as light only on the dark one: make it about 0.3 strong on light and 0.5 on dark. To darken a color in both themes, mix it with `shadow`, not `ink` (which is light in dark mode).
27
27
  - **Fonts that ship:** IBM Plex Sans 400/500/600, Source Serif 4 400/600, IBM Plex Mono 400/500, Latin only. Heavier weights are synthesized by the browser; there is no variable axis, so a weight tween snaps. Chinese falls back to system fonts whose widths differ by machine: never measure text at build.
28
- - **SVG ids are page-wide.** A document can show the same scene twice; give every filter, mask, clip path, gradient and pattern an id made when the scene is built (a counter), never a fixed one. Filters and gradients on a zero-height line need `userSpaceOnUse` regions, or nothing renders.
28
+ - **SVG ids are page-wide.** A document can show the same scene twice, and the reading page shows many scenes at once; give every filter, mask, clip path, gradient, pattern and marker an id made when the scene is built (a counter), never a fixed one. Filters and gradients on a zero-height line need `userSpaceOnUse` regions, or nothing renders.
29
+ - **Arrowheads are shapes, not markers.** A `marker-end` arrowhead shows at the end before its line has drawn there, and a marker with a fixed id (`id="arrow"`) is shared by every scene on the reading page, so hiding or unmounting one scene takes the other scenes' arrowheads with it. Draw one arrowhead element per edge, without an id, and show it when its line arrives.
30
+ - **Drawing a stroke with `pathLength="1"`.** A dash array of `1 1` leaves a stub at the end of a path not yet drawn, because the next dash starts exactly there: use `1 2`. A closed shape (a rounded rect) drawn this way keeps a notch at its starting corner: set `stroke-dasharray` back to `none` once it is drawn. `vector-effect: non-scaling-stroke` measures dashes in screen pixels instead of the path length, so the draw breaks into dashes: leave it off strokes that draw. GSAP's DrawSVG writes its own dash array over any in the CSS, so a dashed line drawn with it turns solid.
29
31
  - **Nothing else animates what a scene moves:** no CSS transitions or `@keyframes` on those elements. A filter or clip path tweens only between the same function lists (`blur(0px)` to `blur(8px)`, never from `none`); remove the filter when it reaches zero.
30
32
  - **Speed effects from speed.** Trails, smears and blur are earlier poses of the same function of time or a function of the velocity of its ease, so they are exact at any seek and vanish at rest.
31
33
  - **A state owns its end.** A step rests at the end of its state (`ms = at(k + 1)`), so that frame must show this state's result. Clamped interval progress (`at(k)` to `at(k + 1)`) gets this for free; a scene that picks a discrete state or round from the time counts the boundary in the earlier one (`ms > at(k + 1)`), or every step rests on the first frame of the next.
32
34
  - **Rest frames stay still.** Springs keep creeping after they look settled and re-rasterize text; snap to the exact end within 0.001. Keep an identity 3D transform at rest instead of removing it, and give `preserve-3d` elements `will-change: transform`: Chromium rasterizes a layer that once had a 3D transform differently, so a frame would depend on how it was reached.
33
35
  - **Pictures** are `<img>` elements (a file in the document's `public/` or a URL): the viewer waits for every `<img>` in the scene and for the fonts before the first frame, so an export opens on the picture. A CSS background image or a picture drawn on a canvas is not waited for; a Three.js scene loads its textures in an async build.
34
- - **Styles:** `frame()` (`gallery/lengths/scenes/kit/frame.ts`) puts the scene's CSS in `@scope`, so two scenes on a page can both style `.card`; a `<style>` written by hand is page-wide. Inside `@scope` a selector matches only below the frame's root. `cqw`/`cqh` inside an element that is itself a size container are that element's units, not the frame's.
36
+ - **Styles:** `frame()` (`gallery/lengths/scenes/kit/frame.ts`) puts the scene's CSS in `@scope`, so two scenes on a page can both style `.card`; a `<style>` written by hand is page-wide. Inside `@scope` a selector matches only below the frame's root. `cqw`/`cqh` inside an element that is itself a size container are that element's units, not the frame's. The page gives every `svg` `max-width: 100%`, which squashes an SVG placed inside a zero-size anchor (a label or icon pinned at a point): give such an SVG `max-width: none`.
37
+ - **Shared modules.** A scene imports other project files with relative `.ts` imports, so the scenes of one piece can share a kit (the frame, the type scale, the colour roles) and a module that draws the central picture and holds the example data: every page then draws the same picture at the same place from the same numbers (`gallery/lengths/scenes/kit/` is such a kit). Changing a shared module changes every page that imports it, so one person owns it ([Team](team.md)). Prefix its class names (`.sm-mark--ok`, not `.ok`): a scene's own `.ok` would take the shared styles, and a tween on a bare selector colours every matching mark on the board. Give it selector functions (`sel.slot(id, i)`) and coordinate functions (`slotCenter(id, i)`) so that pages don't compute positions that break when the shared drawing is resized.
35
38
  - **A list that makes steps** (clicks, messages, screens) needs as many declared states as items; nothing checks the two agree.
36
39
  - **Seeking a one-state scene:** its reading view shows no step buttons (they appear only with more than one state); check seeking with the scrubber (`.pm-scene__scrub`).
37
40
 
@@ -130,7 +133,9 @@ Presmium sets `force3D: false` (so a frame looks the same however it was reached
130
133
  - **Later steps:** `from()` and `fromTo()` apply their start values when the timeline is built. For something that appears in step k > 0, set its hidden state with `gsap.set` (e.g. `drawSVG: 0`, `opacity: 0`, `motionPath: { …, end: 0 }`) and tween it with `to()` or `fromTo(…, { immediateRender: false })` at `s(k)`. Without the `set`, a path drawn in step 2 shows fully drawn during steps 0 and 1.
131
134
  - **A look computed from the time alone** (every element placed by a function of `t`) is `defineScene`, with eases from `gallery/lengths/scenes/kit/fx/time.ts`; a GSAP tween that only drives a clock adds nothing.
132
135
  - **GSAP can't tween `var()` or `color-mix()`:** tween to `color('accent')`; GSAP 3 has no `className` tween. SVG shapes scaled or rotated about their centre need `transform-box: fill-box; transform-origin: center`.
133
- - **Callbacks never fire** (`onUpdate`, `onComplete`, `tl.call`). Numbers: `textContent` with `snap: { textContent: 1 }` or `modifiers: { textContent: v => (+v).toFixed(2) }`. Text swaps: `tl.set(el, { textContent: 'lo' }, time)`, which seeking back undoes.
136
+ - **Callbacks never fire** (`onUpdate`, `onComplete`, `tl.call`), and neither do timers the scene starts (`setTimeout`, `setInterval`): a step reached by seeking runs none of them, so a counter written in `onUpdate` stays frozen. Numbers: `textContent` with `snap: { textContent: 1 }` or `modifiers: { textContent: v => (+v).toFixed(2) }`, or one element per value, each shown with `autoAlpha` at its time. Text swaps: `tl.set(el, { textContent: 'lo' }, time)`, which seeking back undoes.
137
+ - **`x` and `y` don't take `cqw` or `cqh`:** move a frame-relative element with `left`/`top` in percentages, or with `xPercent`/`yPercent`.
138
+ - **`autoRound: false` in a small viewBox.** GSAP rounds pixel-like values to whole numbers, so a `strokeWidth` tween in a `0 0 160 90` viewBox jumps between 0 and 1; set `autoRound: false` on the tween.
134
139
  - **Stagger with `repeat` or `yoyo`:** put them inside `stagger: { …, yoyo: true, repeat: 1 }`; on the tween they repeat the whole wave and run into the next step.
135
140
  - **TextPlugin:** `preserveSpaces: true` keeps indentation in code.
136
141
  - **Randomness:** `"random(...)"`, `stagger.from: 'random'` and `utils.shuffle` use `Math.random`; compute values with a seeded generator and pass function-based values.
@@ -165,7 +170,6 @@ export default animeScene(({ root, anime, at, color }) => {
165
170
  - **SVG transforms:** `translateX`, `scale`, `rotate` are written as CSS `transform`. Put the position on an outer `<g transform>` and animate an inner `<g>` with `transform-box: fill-box; transform-origin: center`.
166
171
  - **A from-value shows from time 0**, before its tween starts. Elements that join later need an opacity tween that keeps them hidden.
167
172
  - **`loop` with a stagger `delay`** repeats the whole staggered group as one iteration; add one tween per element instead.
168
- - **Arrowheads:** a `marker-end` shows before its line is drawn; draw arrowheads as separate shapes that fade in.
169
173
  - **A motion path drawn right to left** turns its label upside down through `rotate`; use only `translateX`/`translateY` from it.
170
174
  - **A head streak is not a drawable with string keyframes:** `['0 0', '0.92 1', '1 1']` splits its duration evenly and runs ahead of a `'0 0'`→`'0 1'` core; draw values past 1 wrap to the start. Drive the streak from one clock (head `E(p)`, tail `E((p − lag) / (1 − lag))`) and write it with the drawable's `setAttribute('draw', …)`.
171
175
  - **A spring from rest rushes through a slow phase:** ease the slow part with a keyframe, then finish with `{ to, ease: spring(…) }`; its settling time may run past the state.
@@ -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
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,159 @@
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 not to use, and the page that introduces it. 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; 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
+
40
+ **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).
41
+
42
+ **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 concepts it introduces, and a step table:
43
+
44
+ | Step | Rest frame and motion | Introduces (each new concept, and the motion that brings it in) | Narration points |
45
+ |---|---|---|---|
46
+
47
+ 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.
48
+
49
+ **H. Conventions after review**, appended by the coordinator (section 6).
50
+
51
+ ## 2. Shared modules and ownership
52
+
53
+ 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:
54
+
55
+ - `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);
56
+ - `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.
57
+
58
+ Scenes import them with relative `.ts` imports ([Libraries](libraries.md), Rules for every library, shared modules). Ownership is by file:
59
+
60
+ - 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.
61
+ - 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.
62
+ - 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.
63
+
64
+ ## 3. One document, many writers
65
+
66
+ There is one `lecture.json`, so writers must not overwrite each other.
67
+
68
+ - **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'.
69
+ - **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.
70
+ - **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.
71
+
72
+ ## 4. Each agent's loop
73
+
74
+ An agent goes through these after every change, on its own pages only:
75
+
76
+ 1. **Check.** `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.
77
+ 2. **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.
78
+ 3. **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.
79
+ 4. **Report** in this form: for each page, its number of steps and one line describing each rest frame; the picture files; the check result; problems found in shared modules; where the page departs from the storyboard and why; what isn't done or isn't good enough.
80
+
81
+ ## 5. The coordinator during production
82
+
83
+ - Dispatch each agent with the storyboard's path, its pages and files, and the reading list of E.1.
84
+ - 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.
85
+ - Forward a pitfall one agent hit to every agent still working, at once; finding it nine times costs more.
86
+ - When every page is done, run the cold read (section 7) before the author sees the piece.
87
+
88
+ ## 6. Review rounds
89
+
90
+ 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.
91
+
92
+ 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.
93
+
94
+ 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 in the term table, and for the colloquial words the register rules out. A hit is renamed, not explained.
95
+
96
+ What the explainer's two rounds had to add, usable as a checklist for the first version:
97
+
98
+ - **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.
99
+ - **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.
100
+ - **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.
101
+ - **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.
102
+ - **The author's decisions**, the term table (before → after) and the table of page titles.
103
+ - **Rules decided in discussion**, written as content the pages must show, with a step table for any new page.
104
+
105
+ 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.
106
+
107
+ ## 7. The cold read
108
+
109
+ 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, 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.
110
+
111
+ **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.
112
+
113
+ **Prepare the material:**
114
+
115
+ 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.
116
+ 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.
117
+ 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.
118
+ 4. Give nothing else: no source, storyboard, term table or notes, or the reader is no longer cold.
119
+
120
+ **First pass: understanding.** Replace the angle brackets; write the prompt in the document's language when the report should be in it.
121
+
122
+ ```
123
+ 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.
124
+
125
+ 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.
126
+
127
+ First, page by page. After each page (all pictures with the same page number), write:
128
+ - what the page says, in one sentence of your own;
129
+ - 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);
130
+ - 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);
131
+ - before you look at the next page, predict what it will say; after it, note whether you were right.
132
+
133
+ At the end:
134
+ - the claim of the whole piece in your own words, in three to five sentences: the problem, the method, why the method solves it;
135
+ - the steps of <the core process, e.g. how one task becomes a state machine>;
136
+ - what you still don't understand;
137
+ - 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".
138
+
139
+ Change no files. Be specific; don't praise what works.
140
+ ```
141
+
142
+ **Second pass: names and register**, sent to the same reviewer once the first report is in, because wording is a cost of understanding too:
143
+
144
+ ```
145
+ Check the wording once more, still changing no files:
146
+ 1. Names: which things are called by several names on different pages? Which word means different things on different pages? List each, with where.
147
+ 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.
148
+ 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.
149
+ 4. In Chinese narration, is a person referred to as 它?
150
+ Add these to the problem list as P0, P1 or P2.
151
+ ```
152
+
153
+ **Use the report:**
154
+
155
+ 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.
156
+ 2. A problem with the method itself, such as a rule whose reason no longer holds, goes to the author; don't decide it.
157
+ 3. The wording problems become one term table in the storyboard, which every page follows.
158
+ 4. Fixes go to the agents that made the pages.
159
+ 5. After the fixes, capture everything again and give it to a new reviewer.
@@ -27,6 +27,7 @@ Terms used throughout:
27
27
  | Write a lecture, revise text, plan pages, write slide text or narration | [Writing](references/writing.md) first, then [Document format](references/document.md) |
28
28
  | Show code, reference project files or run code | [Code](references/code.md) |
29
29
  | Show something moving or explain a process | `presmium-animate` |
30
+ | Make one large piece with several agents in parallel | `presmium-animate/references/team.md` |
30
31
  | Generate voiceover, choose voices, set captions, record or make the video | [Lecture production](references/lecture.md) |
31
32
  | Build a site, slides, PDF, PowerPoint, notebook, translation or student version; prepare offline | [Publishing](references/publishing.md) |
32
33
  | Run a class with quizzes, polls and students following along | [Classroom](references/classroom.md) |
@@ -35,22 +36,24 @@ Terms used throughout:
35
36
 
36
37
  ## Writing in one paragraph
37
38
 
38
- 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. 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.
39
+ 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 in titles, labels and narration; a concept is shown before it is named and used. 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.
39
40
 
40
41
  ## Work through the tools
41
42
 
42
- When a workspace MCP host is connected (the studio's assistant, or an agent connected to `presmium serve`), change the document through its author actions, the same ones the studio's buttons use. Each tool describes its own parameters; this is the order to use them in.
43
+ 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.
43
44
 
44
45
  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.
45
46
  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.
46
- 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; a refusal is final for that request.
47
+ 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`).
47
48
  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.
48
- 5. **Look at the result.** Open the reading preview and the presentation of the changed pages (studio previews, or a build); a successful compile doesn't prove the page reads well or that its steps work.
49
+ 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.
49
50
  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).
50
51
 
51
52
  Undo is `undo_document_change`; `get_document_history` lists the saved changes.
52
53
 
53
- Without an MCP host (working on files in a project), edit `lecture.json` directly and use the command line:
54
+ 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.
55
+
56
+ Without an MCP host that has author actions (working on files in a project), edit `lecture.json` directly and use the command line:
54
57
 
55
58
  ```sh
56
59
  presmium new lesson --type lecture --title 'Lesson'
@@ -6,6 +6,8 @@ Web and agents modify the same `lecture.json`. Read the current document version
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`.
@@ -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
 
@@ -15,6 +15,7 @@ Write these down before the first page. When the request doesn't give the audien
15
15
  - **Core claim**: the one sentence the audience should understand at the end, with its reason: "读完后,读者明白 X,因为看到了 Y". A topic ("讲讲缓存") is not a claim; "第二次取同一本书只要伸手到桌上,所以缓存让重复读取变快" is.
16
16
  - **Forms that matter**: which of the reading page, the slides and the lecture video the author will actually hand out (`metadata.renderers` lists what the document builds: `web`, `notebook`, `slides`, `lecture`). Write the versions that are used; don't fill in a version nobody will see.
17
17
  - **One idea per page**: list the pages as one sentence each before writing any of them. If a page needs two sentences, it is two pages.
18
+ - **Terms**: a table of the concepts the document uses, each with its one name and the synonyms not to use (section 2, "Name each concept once"). A document written by several people or agents doesn't stay consistent without it.
18
19
 
19
20
  ## 2. The information principle
20
21
 
@@ -24,6 +25,7 @@ Every sentence, label, example, figure and page has a reason to exist: it change
24
25
 
25
26
  - **Order by how the audience comes to understand**, not by how the work was done, what was tried first or the history of the field. The reader needs the current state; how it was reached stays out unless the path itself is the lesson.
26
27
  - **Open with what matters**: the first page states the question the audience cares about and the core claim; the first concrete example or the strongest evidence follows right after, not after a long background.
28
+ - **Explain a method before its steps.** A method is what it consists of, the rule by which each part is derived and how each part is checked; the steps of applying it come after that, on one running example. A sequence of step cards (the generic flow on one side, the example on the other) lists what to do without saying why it works, and was rejected for that. Open such a piece with one concrete case of a person doing the task, which carries the question the audience cares about, then what makes it hard, then the model and the one question it has to answer, then the method.
27
29
  - **End by reinforcing**: the last page restates the core claim and what is most worth remembering. It doesn't change position, add caveats or end on a general moral.
28
30
  - **State why it matters**: say what the claim rests on and what it lets the audience understand or solve. Don't leave the reader to infer the value from a table or a figure.
29
31
  - **Compare by goals**: when methods or views differ, explain the difference through what each is for, its conditions and its trade-off ("X 用内存换速度,数据小时更合适"), not through a verdict of better or worse.
@@ -50,6 +52,32 @@ The test for each hit: **would a reader who has read everything up to here plaus
50
52
 
51
53
  When a paragraph has been rewritten three times and still reads heavy, it belongs in another medium: a comparison of three things is a table, a system of parts is a diagram, a process is an animation or a numbered list, a relation between quantities is a formula or a chart. Stop polishing prose in the wrong medium.
52
54
 
55
+ ### Name each concept once
56
+
57
+ A second name tells the audience there is a second thing. In a 19-page explainer written by nine agents, one concept was 委托 on one page and 报障 on another (likewise 认定 and 确认, 回溯 and 返工, 观察 and 现象), and one cost tier had four names; a cold viewer ranked this the largest obstacle to understanding.
58
+
59
+ - **One name per concept** across the whole document: titles, labels, legends, narration and reading text. Keep it in the term table (section 1) with the synonyms not to use.
60
+ - **One concept per name.** "Agent" meant both the agent that drafted the material and the agent under test, drawn in the same colour with the same icon, and viewers concluded that the tested agent wrote its own questions. Two roles get two names, and in pictures two colours.
61
+ - **Sweep at the end**: search the narration, the slide text and the words in scenes for every synonym the table rules out. A hit is renamed, not explained.
62
+
63
+ ### Formal words in the audience's terms
64
+
65
+ - **Titles, labels, legends, metric names and narration use formal written words.** A colloquial label reads as vague or as a joke, and a metric name is something the audience will quote. Only a character's quoted speech, in a speech bubble, keeps the person's own colloquial words.
66
+
67
+ | Colloquial | Formal |
68
+ |---|---|
69
+ | 结论对不对 / 过程折腾了多少 | 结论正确性 / 过程代价 |
70
+ | 和体感对齐 / 能核验 / 能重复 | 与用户感知一致 / 可核验 / 可复现 |
71
+ | 好糊弄 / 乱刁难 / 每次不一样 | 易被说服 / 无依据质疑 / 输出不稳定 |
72
+ | 拉不开 / 拉开 | 无区分度 / 有区分度 |
73
+ | 找对人就是本事 | 定位应协查的团队属于考察内容 |
74
+ | 上游的认定一撤走,下游就站不住了 | 上游结论撤回后,下游结论随之失效 |
75
+ | 一局怎么玩:调查、解释、举证 (a page title) | 单局流程:排查、提交结论、出示证据 |
76
+ | 走错的代价:悄悄认定与回溯 (a page title) | 错误结论的代价:静默确认与结论推翻 |
77
+
78
+ - **The audience's own words, one metaphor system.** Use the everyday terms of the audience's field (an operations engineer says 排查, 协查 and 结案), not a vocabulary borrowed from elsewhere. A metaphor that helps (an evaluation as a game, the user as its non-player character) is mapped once, on one page, term by term; the other pages use the field's words. An explainer that mixed the vocabularies of games, courts, Kubernetes and operations left its viewers translating between four.
79
+ - **A person is named, not 它.** In Chinese, refer to a person by their role (用户, 值班工程师), never 它, which makes them a thing.
80
+
53
81
  ## 3. One page, two versions
54
82
 
55
83
  Each piece of content goes to the version that needs it. Blocks carry `only`, a list of the forms (renderer ids) that show them; a block without `only` appears in every form.
@@ -62,7 +90,7 @@ Each piece of content goes to the version that needs it. Blocks carry `only`, a
62
90
  | The spoken explanation | | ✓ (heard) | The step's narration (`narrations`, named by `narrationIds`) |
63
91
 
64
92
  - **Share the picture, split the words.** The figure or animation is the page's argument and appears in both versions. The reading version explains it in paragraphs; the presentation version labels it with a few words and explains it aloud.
65
- - **Narration is the presentation's explanation.** It is spoken in the lecture video, read by a presenter from the Presenter View, and becomes the speaker notes of an exported PowerPoint. It is never shown on the reading page, so the reading version must not depend on it.
93
+ - **Narration is the presentation's explanation.** It is spoken in the lecture video, read by a presenter from the Presenter View, and becomes the speaker notes of an exported PowerPoint. The reading page shows it only on a page with the `scrolly` layout, in the step track beside the figure (section 6); elsewhere it is not shown, so the reading version must not depend on it.
66
94
  - **Steps follow the shared content.** Drive steps with the figure, the animation or blocks both versions show, and attach the form-limited text to those same steps. A step that only reveals form-limited content is dropped from the other forms: if step 2 of a page only shows slide keywords, that page has one step fewer on the reading page, and the two versions no longer step together.
67
95
  - **Name both presentation forms.** The lecture video uses its own `lecture` view, so a block limited to `["slides"]` is left out of the video; write `["slides", "lecture"]` for text the video should show too.
68
96
  - **Check both versions**: preview the reading page and the presentation of every page you changed (section 7). A page whose reading version is a list of keywords, or whose slide is a wall of paragraphs, put its words in the wrong blocks.
@@ -90,7 +118,7 @@ The reading version is a book chapter. A reader alone must understand it without
90
118
 
91
119
  - **English is written in English order.** Use the subject–verb–object order and idiom of an English textbook; don't carry Chinese topic chains or 的-stacks into English. Prefer active verbs and concrete subjects.
92
120
  - **Punctuation**: Chinese uses full-width punctuation throughout and 顿号(、)between coordinate items. Neither language uses the dash (—, –) as sentence punctuation: split the sentence, use a colon or parentheses, or delete the aside.
93
- - **One term, one word.** Give a term once with its translation if needed, "缓存(cache)", then keep one form. Identifiers (commands, field names, function names) stay verbatim in code formatting and are never translated.
121
+ - **One term, one word** (section 2). Give a term once with its translation if needed, "缓存(cache)", then keep one form. Identifiers (commands, field names, function names) stay verbatim in code formatting and are never translated.
94
122
 
95
123
  ### Paragraphs
96
124
 
@@ -104,22 +132,25 @@ The reading version is a book chapter. A reader alone must understand it without
104
132
 
105
133
  The slide supports a voice; it doesn't replace it. The audience reads the screen and listens at once, so the screen carries what the voice can't: the picture, the structure and a few words.
106
134
 
107
- - **Little text.** A heading that states the page's point, then keywords: short labels beside the part of the picture they name, a number with its unit, a formula's named terms. No paragraphs, no full sentences repeating the narration. Text on screen that duplicates the narration makes it harder to follow than the narration alone.
135
+ - **Little text.** A heading that states the page's point, then keywords: short labels beside the part of the picture they name, a number with its unit, a formula's named terms. No paragraphs, no full sentences repeating the narration, no cards of several lines: a slide of two columns of three-line cards is six paragraphs in boxes, and was rejected as such. Text on screen that duplicates the narration makes it harder to follow than the narration alone; the explanation belongs in the narration. Set limits in characters before writing (one explainer used a label of at most 4 汉字, a value of at most 14, and at most one new line of explanation a step) and keep to them.
136
+ - **Introduce, then name, then use.** A concept first appears through the picture: where it comes from and what it consists of, shown by motion or by a reveal. Its keyword appears beside it after that, and only then do other labels, numbers and the narration use it. A label that relies on something not yet shown ("F3 = 5" before the facts have been numbered) stops a viewer at that slide.
108
137
  - **Graphics where the content has a shape.** When the words describe a relation, turn it into a picture: a flow for a process, a diagram for parts, a timeline for order, a chart for numbers, an animation for change (`presmium-animate`). Graphics carry information and show relations; a paragraph inside a box is still a paragraph. A page whose role is the words themselves (a definition, a rule, a short list of steps, a question, a summary) stays text: don't add a decorative picture or screenshot to fill it.
109
138
  - **Reveal with the voice.** Use steps so each part appears when the narration reaches it, not everything at once on the first beat. One teaching state per step; a reveal binds the explicit IDs of the list items or blocks it shows, never their positions. Narration plays in the order of the step's `narrationIds`.
110
139
  - **Vary the arrangement when the content allows.** The arrangement is how a slide's content is organized: a flow, a comparison, a timeline, a chart, a figure with labels, a code walkthrough, a single statement, a keyword list. (It is not the page's `layout` field, which has only four values.) When several pages in a row share an arrangement because their content has a relation the arrangement hides, reorganize them by that relation; changing colours or icons doesn't make it a different arrangement. Text-only pages in a row are fine when each one's role is its words; never invent a relation or a picture just to vary the look.
111
- - **The heading is a claim.** "缓存命中率" names a topic; "命中率超过 90% 后,加内存几乎不再变快" is the slide's point.
140
+ - **The heading is a claim.** "缓存命中率" names a topic; "命中率超过 90% 后,加内存几乎不再变快" is the slide's point. It is written in formal words like every other label (section 2).
141
+ - **Use the whole slide.** Captions are an overlay the presenter can switch off, so don't keep an empty band at the bottom for them or push the content toward the top. An explainer that kept the bottom 18% free left every slide empty there. Where captions would cover something essential, rearrange the layout.
112
142
  - **Numbers and sources stay honest.** Numbers come from the real run or the cited source. An illustrative value carries a label beside it in the document's language (示意 / illustrative), an estimate likewise (估算 / estimate).
113
143
 
114
144
  ## 6. The narration
115
145
 
116
146
  Narration is a separate script for the ear, written for the presentation version. It is not the reading paragraphs read aloud: the reading version is written for the eye and is too dense to follow by listening.
117
147
 
118
- - **Spoken register, still correct.** Shorter sentences than the reading version, one idea each, the subject near the verb, everyday connectives (所以、可是、接下来). It remains standard Chinese or English: no filler words, no translationese, no chatty asides.
148
+ - **Spoken rhythm, formal words.** Shorter sentences than the reading version, one idea each, the subject near the verb, everyday connectives (所以、可是、接下来). The words stay formal (section 2): spoken rhythm doesn't license colloquial terms such as 折腾 or 拉不开, and a person is 用户 or their role, never 它. It remains standard Chinese or English: no filler words, no translationese, no chatty asides.
119
149
  - **Say what the picture can't show**: the cause, the size, the consequence. Never narrate what is visible ("如图所示,红点越来越多"); say the rule behind it ("一个人传三个,三个传九个").
120
150
  - **No pointing at nothing.** "这里"、"如图"、"看这个" only when the step reveals or highlights that thing at that moment. A cue (a node inside the narration that triggers an action, such as pointing at a block, when the voice reaches it) can do the pointing.
121
151
  - **Budget by time.** A step usually speaks for 6 to 15 seconds: about 20 to 50 汉字 in Chinese (3.5 a second, pauses included) or 15 to 40 words in English (2.5 a second); measure the chosen voice afterwards. A step lasts as long as its narration, so a long script stretches the step while the picture stands still: split the step or trim the script.
122
152
  - **Write for the voice.** Spell out what a synthesized voice can misread: numbers with units ("百分之九十"), symbols, abbreviations and English terms inside Chinese. A word that must be shown one way in the captions and spoken another uses a pronunciation node in the narration (`pronunciation { display, spoken }`) instead of changing the visible text.
153
+ - **Narration that is also read.** On a page with the `scrolly` layout, the reading page keeps the figure in place while a track of the page's steps scrolls beside it, each step showing its narration. There the narration is read as well as heard: each step's narration is complete sentences that make sense beside that step's frame, and a number or symbol keeps its written form, with the spoken form in a pronunciation node.
123
154
  - **Questions turn the talk**: "那如果数组已经排好了呢?" before a turn, with a short pause after it.
124
155
  - **Wording can differ, the claim can't.** Narration may order, simplify and repeat differently from the reading version, but it states the same facts and numbers. When one changes, check the other.
125
156
 
@@ -131,9 +162,9 @@ Review from the seat of someone who hasn't seen the document, not from the seat
131
162
 
132
163
  1. **Read the reading version alone**, start to end, in the reading preview, with the slides and narration out of mind. Mark every place where a term is undefined, a step of reasoning is missing or a sentence depends on something said only in the narration.
133
164
  2. **Watch the presentation with the sound off**: each slide should show its point through the heading and the picture. Then **listen without looking**: the narration should not rely on "这里" or "如图" pointing at nothing.
134
- 3. **Sweep both versions** with the marker table of section 2, and for Chinese, the translationese table of section 4.
135
- 4. **Check the structure**: one idea per page, the core claim on the first page and again on the last, and no run of slides whose shared arrangement hides a relation their content has (section 5).
136
- 5. **Ask a fresh reader** (a person, or a subagent given only the built output) to retell the core claim in their own words and to predict what the next page shows. "Clear" is not a pass; a correct retelling is.
165
+ 3. **Sweep both versions** with the marker table, the term table's banned synonyms and the colloquial words of section 2, and for Chinese, the translationese table of section 4. Include the words inside scenes, which a search of the text blocks misses.
166
+ 4. **Check the structure**: one idea per page, the core claim on the first page and again on the last, every concept introduced before it is used, a method explained before its steps, and no run of slides whose shared arrangement hides a relation their content has (section 5).
167
+ 5. **Ask a fresh reader** (a person, or a subagent given only the built output) to retell the core claim in their own words and to predict what the next page shows. "Clear" is not a pass; a correct retelling is. For a long piece, `presmium-animate/references/team.md` (section 7) has a prompt for a page-by-page cold read and a second pass on names and register.
137
168
  6. **Validate and preview**: `presmium check <document>`, then the reading page and the presentation of the changed pages. Labels and code must be visible, steps reversible and every page's final step complete.
138
169
 
139
170
  Keep IDs when revising: comments, steps and narration stay attached to their blocks. See [Document format](document.md) for the entities and [Publishing](publishing.md) for the outputs.
package/src/cli.ts CHANGED
@@ -6,9 +6,9 @@ import { SkillError } from './resources.ts'
6
6
 
7
7
  export async function main(args: string[]): Promise<number> {
8
8
  const t = MESSAGES[systemLocale()]
9
- let values: { json?: boolean, help?: boolean, name?: string[], 'parent-stdin'?: boolean }, positionals: string[]
9
+ let values: { json?: boolean, help?: boolean, name?: string[], update?: boolean, 'parent-stdin'?: boolean }, positionals: string[]
10
10
  try {
11
- const parsed = parseArgs({ args, allowPositionals: true, options: { json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' }, name: { type: 'string', multiple: true }, 'parent-stdin': { type: 'boolean' } } })
11
+ const parsed = parseArgs({ args, allowPositionals: true, options: { json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' }, name: { type: 'string', multiple: true }, update: { type: 'boolean' }, 'parent-stdin': { type: 'boolean' } } })
12
12
  values = parsed.values; positionals = parsed.positionals
13
13
  if (values.help) { process.stdout.write(t.usage); return 0 }
14
14
  if (positionals.length !== 2 || positionals[0] !== 'install') throw new Error()
@@ -23,8 +23,8 @@ export async function main(args: string[]): Promise<number> {
23
23
  if (process.stdin.readableEnded || process.stdin.destroyed) stop()
24
24
  }
25
25
  try {
26
- const result = await installBundledSkills(positionals[1]!, { names: values.name, signal: controller.signal })
27
- process.stdout.write(values.json ? `${JSON.stringify(result)}\n` : `${t.installed(result.installed.length, result.skipped.length)}\n`)
26
+ const result = await installBundledSkills(positionals[1]!, { names: values.name, signal: controller.signal, update: values.update })
27
+ process.stdout.write(values.json ? `${JSON.stringify(result)}\n` : `${t.installed(result.installed.length, result.skipped.length, result.updated.length)}\n`)
28
28
  return 0
29
29
  } catch (error) {
30
30
  const code = error instanceof SkillError ? error.code : 'skill-unavailable'
package/src/install.ts CHANGED
@@ -1,12 +1,17 @@
1
1
  import { createHash } from 'node:crypto'
2
- import { link, lstat, mkdir, mkdtemp, realpath, rm, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
2
+ import { link, lstat, mkdir, mkdtemp, realpath, rename, rm, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
3
3
  import type { Stats } from 'node:fs'
4
4
  import { dirname, join, resolve } from 'node:path'
5
5
  import { resourceBytes, resourceFiles, skillDirectory, skillName, SKILL_NAMES, SkillError } from './resources.ts'
6
6
  import type { SkillName } from './resources.ts'
7
7
 
8
- export interface InstallSkillsOptions { names?: readonly string[], signal?: AbortSignal }
9
- export interface InstallSkillsResult { installed: SkillName[], skipped: SkillName[] }
8
+ export interface InstallSkillsOptions {
9
+ names?: readonly string[]
10
+ signal?: AbortSignal
11
+ /** Replace the skills installed before (by an earlier Presmium) with this version's; links and files are still kept. */
12
+ update?: boolean
13
+ }
14
+ export interface InstallSkillsResult { installed: SkillName[], skipped: SkillName[], updated: SkillName[] }
10
15
  const missing = (error: unknown) => (error as NodeJS.ErrnoException).code === 'ENOENT'
11
16
  const present = async (path: string) => { try { return await lstat(path) } catch (error) { if (missing(error)) return undefined; throw error } }
12
17
  const same = (a: Stats, b: Stats | undefined) => Boolean(b?.isDirectory() && !b.isSymbolicLink() && a.ino === b.ino && a.dev === b.dev)
@@ -33,11 +38,17 @@ export async function installBundledSkills(projectDir: string, options: InstallS
33
38
  catch { throw new SkillError('skill-project-invalid') }
34
39
  try {
35
40
  const destination = await directories(root)
36
- const result: InstallSkillsResult = { installed: [], skipped: [] }
41
+ const result: InstallSkillsResult = { installed: [], skipped: [], updated: [] }
37
42
  for (const name of names) {
38
43
  cancelled(options.signal)
39
44
  const target = join(destination, name)
40
- if (await present(target)) { result.skipped.push(name); continue }
45
+ const existing = await present(target)
46
+ if (existing && options.update && existing.isDirectory() && !existing.isSymbolicLink()) {
47
+ await replaceSkill(destination, target, name, options.signal)
48
+ result.updated.push(name)
49
+ continue
50
+ }
51
+ if (existing) { result.skipped.push(name); continue }
41
52
  const source = skillDirectory(name)
42
53
  const temporary = await mkdtemp(join(destination, `.presmium-${name}-`))
43
54
  let reserved: Stats | undefined
@@ -102,3 +113,29 @@ export async function installBundledSkills(projectDir: string, options: InstallS
102
113
  return result
103
114
  } catch (error) { if (error instanceof SkillError) throw error; throw new SkillError('skill-install-unsafe') }
104
115
  }
116
+
117
+ /** The skill's directory replaced as a whole by this version's: written aside, then swapped in by two renames. */
118
+ async function replaceSkill(destination: string, target: string, name: SkillName, signal?: AbortSignal): Promise<void> {
119
+ const source = skillDirectory(name)
120
+ const temporary = await mkdtemp(join(destination, `.presmium-${name}-`))
121
+ const previous = `${temporary}-previous`
122
+ try {
123
+ for (const path of resourceFiles(source)) {
124
+ cancelled(signal)
125
+ const file = join(temporary, path)
126
+ await mkdir(dirname(file), { recursive: true })
127
+ await writeFile(file, resourceBytes(source, path), { flag: 'wx' })
128
+ }
129
+ cancelled(signal)
130
+ await rename(target, previous)
131
+ try {
132
+ await rename(temporary, target)
133
+ } catch (error) {
134
+ await rename(previous, target)
135
+ throw error
136
+ }
137
+ await rm(previous, { recursive: true, force: true })
138
+ } finally {
139
+ await rm(temporary, { recursive: true, force: true })
140
+ }
141
+ }
package/src/messages.ts CHANGED
@@ -2,15 +2,15 @@ import type { SkillErrorCode } from './resources.ts'
2
2
 
3
3
  interface SkillMessages {
4
4
  usage: string
5
- installed(installed: number, skipped: number): string
5
+ installed(installed: number, skipped: number, updated: number): string
6
6
  errors: Record<SkillErrorCode, string>
7
7
  usageError: string
8
8
  }
9
9
 
10
10
  export const MESSAGES: Record<'zh-CN' | 'en', SkillMessages> = {
11
11
  'zh-CN': {
12
- usage: '用法:presmium skills install <目录> [--name <技能>] [--json]\n\n将缺少的 Presmium 技能安装到项目的 .agents/skills;已有内容保持不变。\n',
13
- installed: (installed, skipped) => `已安装 ${installed} 项技能,保留 ${skipped} 项已有技能。`,
12
+ usage: '用法:presmium skills install <目录> [--name <技能>] [--update] [--json]\n\n将缺少的 Presmium 技能安装到项目的 .agents/skills;已有内容保持不变。\n加 --update 时,把已有的技能目录换成这个版本的技能(例如升级 Presmium 之后);链接与文件仍然保留。\n',
13
+ installed: (installed, skipped, updated) => `已安装 ${installed} 项技能,${updated ? `更新 ${updated} 项,` : ''}保留 ${skipped} 项已有技能。`,
14
14
  usageError: '请使用 install <目录>,或通过 --help 查看用法。',
15
15
  errors: {
16
16
  'skill-not-found': '没有这项内置技能。请从技能目录中选择。',
@@ -24,8 +24,8 @@ export const MESSAGES: Record<'zh-CN' | 'en', SkillMessages> = {
24
24
  },
25
25
  },
26
26
  en: {
27
- usage: 'Usage: presmium skills install <directory> [--name <skill>] [--json]\n\nInstall missing Presmium skills in the project’s .agents/skills; existing entries are preserved.\n',
28
- installed: (installed, skipped) => `Installed ${installed} skills; preserved ${skipped} existing skills.`,
27
+ usage: 'Usage: presmium skills install <directory> [--name <skill>] [--update] [--json]\n\nInstall missing Presmium skills in the project’s .agents/skills; existing entries are preserved.\nWith --update, existing skill directories are replaced with this version’s skills (after upgrading Presmium, for example); links and files are still preserved.\n',
28
+ installed: (installed, skipped, updated) => `Installed ${installed} skills${updated ? `, updated ${updated}` : ''}; preserved ${skipped} existing skills.`,
29
29
  usageError: 'Use install <directory>, or --help for usage.',
30
30
  errors: {
31
31
  'skill-not-found': 'This bundled skill does not exist. Choose one from the skill catalog.',
package/src/resources.ts CHANGED
@@ -47,9 +47,10 @@ export function skillDirectory(name: string): string {
47
47
  const packed = join(PACKAGE_DIR, 'skills', selected)
48
48
  const source = join(REPOSITORY_SKILLS, selected)
49
49
  try {
50
- const bundled = lstatSync(packed, { throwIfNoEntry: false }) !== undefined
51
- const dir = bundled ? packed : !PACKAGE_DIR.split(sep).includes('node_modules') ? source : packed
52
- if (lstatSync(bundled ? join(PACKAGE_DIR, 'skills') : REPOSITORY_SKILLS).isSymbolicLink()) throw new SkillError('skill-path-invalid')
50
+ // In the repository the skills are read where they are written: the packed copy is made by prepack and may be older.
51
+ const fromSource = !PACKAGE_DIR.split(sep).includes('node_modules') && lstatSync(source, { throwIfNoEntry: false }) !== undefined
52
+ const dir = fromSource ? source : packed
53
+ if (lstatSync(fromSource ? REPOSITORY_SKILLS : join(PACKAGE_DIR, 'skills')).isSymbolicLink()) throw new SkillError('skill-path-invalid')
53
54
  const stat = lstatSync(dir)
54
55
  if (stat.isSymbolicLink() || !stat.isDirectory()) throw new SkillError('skill-path-invalid')
55
56
  return realpathSync(dir)