Repository documentation

A plan before surprises — performance score

Status: implemented in the directed renderer; user visual validation pending. The user approved the voices and rejected the first cut's animation. Review decision binds that verdict to the original audition. story.json remains the exact spoken-dialogue authority; this score adds the missing visual narrative without changing approved audio or provenance.

Direction and notation

The scene moves from protecting an existing repository, through uncertainty about mutation, to understanding the boundary between a plan and earned evidence. Sam's behavior changes as that concern is resolved. LitAI watches and responds to Sam's concern rather than gesturing continuously at the audience.

Each numbered turn below pairs the exact dialogue with its teaching objective, phrase cues, speaker action, listener reaction, focus and resting state. Quoted cues anchor actions to heard words in retained recordings, not a percentage of turn duration. Before rendering, mark cue times from those recordings and retain that timing map. Do not guess word boundaries from sentence length. If a beat cannot fit naturally, simplify the action; do not speed up the approved speech.

Actions need anticipation, a readable meaningful pose, and a settle. A hold is an intentional performance choice. Use one focal action at a time; the listener's reaction follows it and must not compete with a command or diagram. Hands move to a concrete target or express a specific thought, then rest. No recurring arm wave, nod-on-every-line, automatic pointing, or random idle movement is a substitute. Natural blinking and subtle breathing may support presence only if unobtrusive.

Use the established Sam and LitAI identities. Keep a stable two-shot with a shared work surface and central explanation panel. Focus changes through eyelines and local emphasis first; no decorative camera bobbing or compulsory cut per turn. All proposed UI/props are explanatory artwork, not captured execution. Keep that walkthrough label visible and captions clear. No animated action executes a command.

1. existing — ownership concern

Sam: “I have a working repository. Please tell me onboarding doesn't mean rewriting it.”

Objective: Make Sam's concern tangible before offering a solution.

• Opening state / focus: Sam's hand rests protectively on a folder labelled “Existing source”; its contents remain visible and unchanged throughout the scene. LitAI faces Sam, hands at rest. The folder, not an arm movement, establishes the problem.
• Cue “working repository”: Sam looks at the folder with quiet confidence.
• Cue “rewriting it”: Sam turns their eyes to LitAI, with a questioning brow and a slight protective pull of the folder. One small action, no repeated tugging.
• Listener / end hold: LitAI receives the question without nodding over it. Hold Sam's questioning look into the answer. Do not show a rewrite or erase files.

2. doctor — an inspection path

LitAI: “It doesn't. Start with doctor, then ask for an adopt plan. Your source stays yours.”

Objective: Show inspection as a sequence that leaves the repository alone.

• Cue “It doesn't”: LitAI meets Sam's eyeline with a calm, small head shake; hands remain still. Let the reassurance land before presenting commands.
• Cue “doctor”: LitAI turns toward the litai doctor card. One open-hand indication directs attention there; hold it long enough to read the command.
• Cue “adopt plan”: Shift panel emphasis to litai onboard adopt and a preview sheet. Shift gaze rather than adding another arm sweep. These are steps to inspect, not fabricated successful terminal results.
• Listener / cue “source stays yours”: Sam releases the protective grip but leaves the folder in place. This is the first visible change in trust.
• End hold: Both look at the preview; LitAI's hand settles. The source stays intact.

3. changes — distinguish inspection from mutation

Sam: “And when I run that command, what changes?”

Objective: Expose the ambiguity the next answer must resolve.

• Opening focus: The preview and a separate, inactive “Apply (acknowledgement required)” control are visible. They are not a single combined operation.
• Cue “what changes”: Sam looks from the preview toward Apply and lifts a hand toward it, stopping before contact. A held hesitation communicates the question.
• Listener / end hold: LitAI follows Sam's gaze, ready to clarify the boundary. No click, file change, progress indicator or success state occurs.

4. readonly — a visible boundary

LitAI: “The plan is read-only. Review the files and the recorded checks. Applying it is a separate, acknowledged step.”

Objective: Resolve Sam's hesitation with a readable preview/apply separation.

• Cue “read-only”: Emphasize the preview's “Read-only plan” label and its boundary. LitAI looks at that boundary; hands rest while the viewer reads.
• Cue “files and the recorded checks”: Reveal the preview's proposed-file list and readiness observations. Use the retained adopt-plan evidence for any factual values; these observations are not build/test/acceptance passes.
• Cue “separate, acknowledged step”: Give the gap between preview and inactive Apply control a single visual emphasis. LitAI indicates the gap once, then settles.
• Listener / end hold: Sam lowers the hovering hand without touching Apply. Hold the separation; no mutation or acknowledgement has happened.

5. green — test the wrong inference

Sam: “Good. And a green plan means the project's ready to ship?”

Objective: Make the tempting inference visible without asserting it as true.

• Cue “Good”: Sam's posture relaxes. Avoid an extra approval nod.
• Cue “green plan”: Sam looks at plan readiness, then toward a proposed “Ready to ship?” question card. Do not paint an actual shipping-success badge.
• Cue “ready to ship”: One questioning brow and the held eyeline carry the challenge; hands stay down.
• Listener / end hold: LitAI looks from the question back to Sam. Leave the question unanswered on screen until the response.

6. earn — evidence has separate gates

LitAI: “No. It means we're ready to discuss the next step. Builds, tests, and independent acceptance still have to earn their evidence.”

Objective: Replace the false equivalence with distinct, still-unearned gates.

• Cue “No”: A brief still hold and one small head shake. The shipping question remains a question; do not replace it with a red failure result either.
• Cue “next step”: Return focus to the plan as the starting point for discussion.
• Cues “Builds”, “tests”, “independent acceptance”: Emphasize those three named gates in spoken order. LitAI follows them with gaze; do not point three times. All remain visibly pending, without invented check marks or progress scores.
• Cue “earn their evidence”: Show an unfilled evidence-record outline associated with the gates. LitAI's open hand briefly presents that relationship, then rests.
• Listener / end hold: Sam follows the sequence, ending on the evidence outline. Hold the distinction “Plan readiness ≠ shipping qualification” for reading.

7. surprises — earned resolution

Sam: “A plan before surprises. I can work with that.”

Objective: Show the concern resolved through understanding, not sales enthusiasm.

• Cue “plan before surprises”: Sam places the unchanged folder beside the plan, choosing to inspect it. No source moves into a conversion machine or new owner.
• Cue “I can work with that”: One earned nod and a relaxed resting pose.
• Listener / end hold: LitAI acknowledges with a warm expression, hands still. Let the quiet shared attention carry the rapport. No synchronized waving.

8. inspect — hand attention to the actual task

LitAI: “Let's inspect yours.”

Objective: Invite the next concrete step and get the presenters out of its way.

• Cue “inspect”: LitAI makes one small open-hand invitation toward the plan view; Sam looks there. Both then settle rather than waving at the viewer.
• Final focus / hold: Keep the actionable command and read-only distinction legible. Transition to a real captured plan in the next chapter only when fresh evidence exists. Do not imply this audition inspected the viewer's repository.

Realization requirements and review

The directed player.mjs consumes the executable performance through performance.mjs and the retained cue map. It replaces the old generic arm cycle with 46 finite pose/focus beats across all 23 phrase cues. Two-joint working arms are composited above the desk and panel; gaze, brow, expression and a source folder carry the speaker/listener direction. The other arm rests. The stable two-shot is retained without camera motion; folder placement is a small slide beside the preview. These are deliberate staging choices, not a claim of full-body or 3D acting. No direction silently falls back to the old loop.

Cue times are local Whisper word-timestamp estimates mapped to approved script phrases. Raw recognition includes errors (for example, splitting “working” into “work in”); it is not a replacement transcript or pronunciation assessment. The cue map retains raw word spans, tool/model and recording identities. Timing and performance remain subject to the user's moving-cut review. Previous takes and approved WAVs are preserved.

Build inputs bind this narrative, executable score, exact dialogue/turn identities, estimated cue map, prop/rig assets and renderer. Admission validates cue existence, word-span timing, recording identity, supported targets, bounded pose channels and turn coverage. Browser checks validate intentional holds, the hover gap, pending gate emphasis, adjacent-frame continuity, finite seeking and repeatability. Those structural checks establish that a score was followed; they cannot establish good acting.

Review the complete moving sequence at playback size and speed with its approved soundtrack, then once muted to inspect staging. For every movement, the reviewer must be able to name the thought, relationship or learning step it communicates. Remove a motion that has no answer. Check anticipation, readable holds, clean settles, coherent eyelines, listener reactions and one focal action at a time. Compare with the still fallback: movement should clarify something or create an earned conversational response. Record voice, factual, motion and accessibility verdicts separately. A contact sheet or unchanged pixel hash cannot pass this review.

Reduced-motion/static output must preserve the same explanation with settled poses, visible preview/apply separation, pending gate labels and full captions/transcript. No fact may depend on seeing a hand move. Validate that mode separately; do not make reduced motion remove essential evidence or instructions.