[immakermatty]

Motivation

On 2026-10-25 Matěj (Organization Admin) played the guide (a "?" tour step) on his Osobní Prostředí with Buddy: "ještě vyskočí lazurio kámen namísto buddyho, jako je to v prototypu" ("the Lazurio stone still jumps out instead of Buddy, as he does in the prototype").

• Root decision 0210, point 1: the neutral Lazurio guide is only for a person without Buddy. Where his bubble shows, Buddy is the guide.
• Why the stone was still there: F56 point 6 drew the neutral mark everywhere ("Buddy's character comes with his bubble"), because no Buddy origin existed yet. F60 point 5 only made the mark start at his launcher.
• The prototype (HumanAndMachine-ai/prototypes-lazurio 8d13cac6: GuideOverlay.tsx, guide.css, guide.ts, docs/buddy-guide.md): Buddy jumps out of his bubble, stands beside the element, points at it and says the step in a speech bubble.

Stacked on #647 (base agent/DEV-6676-bubble-corner, now at 5e06d75, which this branch includes).

What changes (F56 addendum (7) of 2026-10-25)

• Who presents. Where the page shows Buddy's bubble, the engine names him in the step it draws: GuideView.buddy carries his picture (/assets/avatar.webp of his origin) and his name, as his launcher shows them. It comes from the same fact that already lets his frame ask and invites nobody to get a Buddy, so there is one answer to whether Buddy is here.
• His figure (guide-layer.ts, guide-styles.ts), as the prototype's .gbuddy:
  • his picture 48 × 56 px in a 56 × 64 box, no disc, a soft shadow, pixels kept sharp (object-fit: contain, so the 192 × 208 sprite is not stretched);
  • he leaps out of his launcher, hops to every step and back, and breathes while he stands;
  • his hand, a 22 px blue disc with Iconoir's ArrowLeft (icons.ts), points at the element and pokes;
  • all motion only where it is not reduced; with less motion he appears in place.
• Where he stands (guideBuddyPlacement in guide-placement.ts, pure, a port of the prototype's placeGuide):
  • 30 px beside the element: right, else left, else below, else above;
  • the card 10 px past him, 24 px higher beside an element on its right or left;
  • without an element, the card in the middle and he on its left;
  • below 768 px the card stays the sheet, and he stands on its top edge.
• The card is his speech bubble. Its tail points at his head instead of the element. The title loses the indent the stone's disc needed. Its accessible name is "Buddy: <title>" instead of "Průvodce Lazuriem: <title>", so a screen reader hears who presents.
• His launcher waits empty while he is out, from his leap until he is back, as the prototype's .buddyw__launcher.is-away.
  • The bubble's model carries launcher.away; the view draws data-away (paper with a grey ring, no picture); the layer says when he leaves and when he is back.
  • The launcher still opens his window, and --lazurio-buddy-clearance stays, since its place is still taken.
• Where his picture does not load, the neutral stone (40 px white disc) stands in his place, with his hand, as on his launcher.

What it does not change

• The words: the explanations, their texts, steps, scenes, documentation links and the invitation.
• The logic: the engine's rules (never two tours at once, who may ask, Escape and focus), the ring and the dimmed page.
• The guide without Buddy: the stone at the card's corner, and the card placed as the tour's bubble.
• Interface v1: no new name. GuideView and the bubble's model are internal.
• The card's size and the timing: its width (300 px or the sheet) and the layer's 0.7 s travel. The prototype has a 352 px card beside a scene and 0.9 s.
• The Folder: no template change.

Verification

• bun run check:static (lint, typecheck, public guard, proof build and smoke): pass.
• bun test over the 45 test files that touch src/shell: 917 pass, 0 fail.
  • tests/shell-guide.test.ts:
    • the prototype's distances on every side, in the middle and on the sheet;
    • one rule over three window sizes and a grid of elements: he and his card stay inside the window and apart, off the element, 30 px from it on the side he points from, the card 10 px past him, its tail at him;
    • the neutral guide's step carries no Buddy.
  • tests/shell-buddy.test.ts:
    • with his bubble, every step names his picture and name, with exactly the same explanations, steps, scenes and words as without him;
    • the launcher's away: said once, kept across another origin, back once he is back.
• Headless Chrome (root decision 0178) against scripts/preview-launchpad.ts personal cs … owner buddy (Buddy's origin serving T3 Code's real avatar.webp) and the same preview without buddy. Apps home "?" (environment), steps 1 and 2, then Escape, at 1440 and 390 px:
  • with Buddy, 1440 px:
    • step 1: he stood 30 px right of the Environment picker, hand toward it; the card was 10 px past him, its tail 41 px down, named "Buddy: …";
    • step 2: he stood left of the browser toggle, with the card on his left;
    • the launcher was empty while he was out, with the clearance unchanged, and showed him again once he was back after Escape;
  • with Buddy, 390 px: he stood on the sheet's top edge, without a hand;
  • picture refused (404): the stone stood in his place with his hand; the launcher showed its stone too;
  • prefers-reduced-motion: he appeared in place; after Escape the launcher showed him at once;
  • without buddy: the stone at the card's corner, as before, named "Průvodce Lazuriem: …", and no launcher.

Risks and open questions

• Choices the prototype leaves open, which are mine and for Matěj's review:
  • Buddy on top of the sheet below 768 px;
  • the stone in his place when his picture fails;
  • the card's accessible name;
  • keeping the card's width and the 0.7 s travel.
• Not checked: Safari and Firefox, and the forks' pages (T3 Code, MausBot), where Buddy presents principles his frame asks for. They use the same shell code.
• Release: rides with Buddy's launcher in one bottom-right corner with his figure as in the prototype, and a full screen over the whole window (DEV-6676, F60 addendum) #647's Platform release, after the forks read --lazurio-buddy-clearance.

🤖 Generated with Claude Code

Note

Have Buddy present guide steps with his own bubble, hand pointer, and animations

• When a page shows the Buddy bubble, Buddy now presents guide explanations instead of the neutral Lazurio mark. His figure and speech bubble animate out from the launcher and hop between steps, with a directional hand pointer toward the target.
• The launcher empties into a paper-colored disc while Buddy is away, and Buddy's picture, name, and away state flow through a new nullable GuideBuddy presenter seam in guide.ts.
• New placement logic in guide-placement.ts computes Buddy and card positions around the target, with narrow-viewport sheet layout, no-anchor centering, and margin clamping. It enforces a 30-pixel anchor gap and 10-pixel card-to-Buddy gap.
• Falls back to the neutral guide mark when Buddy's avatar fails to load or no bubble is available. Reduced-motion and still-layer settings skip the new animations, matching existing guide behavior.
• Risk: GuideView gains a required presenter field and GuideSeams.buddy changes from a boolean to a nullable GuideBuddy result, so any out-of-tree seam implementations or guide view consumers need updating; see guide.ts and guide-layer.ts.

^{Macroscope summarized 704b68d.}

[agentrozjedemeai]

APPROVED — exact-head Steward QA, 45c41f502b9a8b34a6d38d144534feebeff3ef76 (base 5e06d756314c779b911d2d90451c917446954e57).

Ověřil jsem diff vůči #647 a vazbu na původní placeGuide: rozhodnutí o prezentujícím jde ze stejné Buddy podmínky, obsah a kroky průvodce zůstávají, rozhraní v1 se nemění. Figura bez disku, ukazující ruka, řečová karta, rozestupy (30/10/24 px), mobilní list, návrat do prázdného launcheru i zachované odsazení od něj odpovídají implementaci. Při nedostupném obrázku se v pozici figury vykreslí neutrální značka; karta používá přístupný název „Buddy: …“. Animace jsou vypnuté při omezeném pohybu.

V izolovaném checkoutu přesně tohoto headu: git diff --check čistý; bun test tests/shell-guide.test.ts tests/shell-buddy.test.ts 200 úspěšných / 0 chyb; bun run check:static úspěšný. Živé CI je zelené, žádná otevřená review vlákna. Addendum uvádí konkrétní rozhodnutí i limity: Safari, Firefox a stránky forků zde nebyly ověřeny. Autorův Chrome smoke neopakuji jako svůj důkaz. Jen review — bez merge, push či release.

The base branch was changed.

[agentrozjedemeai]

APPROVED — exact-head QA for 704b68d against main b5ecc58.

The single guide commit is a clean rebase of the previously approved 45c41f5: stable patch-id is 7918d077faea3ce54312c59d4ae13009089f5359 for both. Guide source, tests and guide documentation are byte-identical; the F56 guide addendum is byte-identical as well. The only change between the trees in this area is the F64 addendum from #652, already on main and unchanged by this PR. #652 changes Buddy persona refresh in the Launchpad server/controller, not the guide presenter or shell; the combined head passed the relevant integration tests.

In a fresh isolated checkout: git diff --check clean; bun test on shell-guide, shell-buddy, buddy-persona, buddy-persona-save and launchpad-buddy: 273 pass, 0 fail; bun run check:static pass. CI on this head: static and both test shards green, required aggregate check green. No open review threads. This is a review only; I did not merge, push or release. Browser smoke from the prior review was not repeated on this rebase.