[immakermatty]

Why

People who arrive in Lazurio are confused until they understand a few principles. The Launchpad's pages carry explaining sentences that a person has to read before they can act. Matěj decided on 2026-10-18 (root decision 0180, addendum of 2026-10-18) that a "?" beside a page's heading makes Buddy explain the page in place:

• the host's shell draws the ring, the character and the card;
• Buddy's frame may only ask by id;
• without Buddy, a neutral Lazurio guide explains the same way.

This is slice PR 4 of the DEV-6612 Launchpad lane (plan DEV-6612-produkt-jedna, milestone M3, shaping section 3(c) "„?“ → Buddy na místě"). Variants of an explanation follow #499: they come only from facts the host knows, never from an Organization's name. The reference is the approved wireframe (HumanAndMachine-ai/prototypes-lazurio bebea85, docs/buddy-guide.md).

The decision is recorded as F56 in docs/decisions.md.

What it adds

The guide's engine lives in the shell (src/shell/), so the Launchpad, the Dashboard (by its pin) and the T3 Code and MausBot forks share one engine and one check of who may ask:

• guide.ts decides what plays and when, over seams, so it is tested without a DOM.
• guide-layer.ts draws in <lazurio-buddy>'s own shadow root: the ring, the neutral guide's mark (the Lazurio symbol on a white disc), the card, placement, motion with prefers-reduced-motion, Escape and focus.
• guide-styles.ts is the layer's stylesheet.
• guide-content.ts holds the six principles in Czech and English: Prostředí, Osobní Prostředí, kam smějí agenti, Soubory, Integrace and Trezor. They use the wireframe's ids and follow the text rules. Kind tokens are filled from the shell's kind facts (automated counts as work), your computer gets its own words, and the Personal Environment gets its own Trezor version.
• guide-placement.ts is the pure placement rule, moved unchanged from src/launchpad/tour-placement.ts; the Launchpad's tour now uses it from there. The guide adds two things: without an element its card stands centred, and below 768 px the card is a sheet at the foot of the window.
• Attention arbiter: never two tours at once. While Začínáme wants attention, a "?" plays nothing and draws nothing next to the tour's bubble. Instead the tour's bubble nudges, and assistive technology hears "Nejdřív dokončete Začínáme". While the guide is out, the tour waits.

Additions to interface v1 (permanent, kept as few as possible):

Name	Why
<lazurio-buddy lang>	The guide's place on a page and its language. The forks already place this element, undefined.
marks: data-guide, data-guide-help	A step points at a mark rather than a selector, so an explanation never names the page's structure. The "?" names the explanation it plays.
event lazurio-guide ({type: "started" | "done" | "closed", explainer})	Lets a host follow the guide.
export provideGuides	A host hands over the explanations of the page it shows, at runtime. Those explanations belong to the host because they point at its own elements.

Without explanations handed over and without a Buddy origin, <lazurio-buddy> draws nothing, listens to nothing and keeps nothing: no shadow root, no listener, no subscription. So the forks do not change after rollout. The following are not promised:

• the principles' ids, texts and marks;
• the shell's own marks;
• the Launchpad's arbiter guideAttention (not exported by shell.js).

The lazurio.guide.* v1 protocol (src/shell/guide-protocol.ts, pure, with vectors in src/shell/guide-vectors/v1/guide-protocol.json, run through F50's vector runner and format):

• The frame sends {type: "lazurio.guide.play", v: 1, explainer}.
• The host accepts it only if all of these hold:
  • it comes from the bubble frame's own window;
  • its origin is exactly Buddy's origin as the shell document names it (https, never taken from the message);
  • its keys are exactly type, v and explainer;
  • v is 1;
  • explainer is a known id, either a principle or an explanation of the current page;
  • nothing is playing and Začínáme does not want attention. If something is playing or Začínáme wants attention, the host answers busy instead.
• Anything refused is dropped without an answer.
• Replies are {type: "lazurio.guide.started|done|closed|busy", v: 1, explainer, kind?}, posted to the exact origin, never *.
• No listener is registered in this release. The receiver (createGuideReceiver) and the vectors ship now, so PR 7 only wires them up once Buddy has an origin (M7).

On the Launchpad, Soubory is the first page with a "?":

• The "?" sits right after the heading in the breadcrumb and calls the engine directly, not through postMessage.
• It plays the principle files. In a Team Environment it plays the Launchpad's own files-team, chosen by the kind alone (src/launchpad/guides.ts).
• New marks: nav-files and files-list.
• In the same PR, the sentences the "?" replaces are removed. The Launchpad's real Files page never had the prototype's line "S čím pracují vaši agenti."; its counterparts were these, all now gone:
  • the introduction "Složka Dokumenty tohoto Prostředí. Agenti sem ukládají…" / "The Documents folder of … Agents save finished files here…" (the counterpart of "S čím pracují vaši agenti.");
  • the Team note "Toto Týmové Prostředí je sdílené…" / "This Team Environment is shared…" (the counterpart of the prototype's "Celý Team může tyto soubory číst a měnit.", now said by files-team);
  • the empty Documents folder's explanation, now only "Zatím žádné soubory." / "No files yet." (the counterpart of the prototype's "Nahrajte podklady pro agenty.").

What it deliberately does not do yet

• No Buddy frame, origin or listener, and no Buddy character. Everyone is guided by the neutral guide. That comes with PR 7, after M7.
• No "?" on other pages. Apps, Integrace, Trezor and every Settings section come in PR 5. The principles other than files cannot be reached from the Launchpad yet, and the host marks they look for come with PR 5.
• No motion scenes for the principles. Those are PR 6.
• No change to the column head, the band, "Dokončit nastavení" or the rail, which belong to the T3 Code rebuild thread. The shell's own marks (tab-chat, picker, …) are found by selectors inside those elements without touching their code.
• No change to the Trezor page content (DEV-6631), and no change to Launchpad: the tour's gear stop for AI is its title alone #475's files.

Verification

• bun run check:static: lint, typecheck, public check, proof build and smoke.
• Focused tests: tests/shell-guide-protocol.test.ts, tests/shell-guide.test.ts, tests/launchpad-guide.test.ts, tests/shell-interface.test.ts, tests/launchpad-shell-routes.test.ts, tests/tour-placement.test.ts, tests/first-run.test.ts.
  Together, 230 pass and 0 fail.
• Full suite: bun test --timeout 30000 gave 4148 pass, 9 skip, 0 fail (4157 tests in 284 files). It ran on the tree just before the unused playGuide export was removed; the run on this exact head is noted in a comment below.
• Headless Chromium against the hosted scripts/preview-launchpad.ts, on Soubory, in Czech and English, in a Work and a Team Environment, at 1440 and 700 px, and at 1440 px with prefers-reduced-motion:
  • The "?" is named "Jak to funguje?" / "How does it work?". Before any click, <lazurio-buddy> has no shadow root.
  • Work Environment. The "?" plays the principle files. The ring sits exactly on the column head's Chat tab for steps 1–3 and on the Soubory item for step 4. The steps advance with Enter, and the last button reads "Rozumím" / "Got it".
  • Team Environment. The "?" plays files-team. The ring is on the Chat tab, then on the file list.
  • At 700 px the card is a sheet at the window's foot. Steps that point into the folded column show no ring; the list is ringed.
  • Escape closes the guide, and focus returns to #page-help.
  • Reduced motion. The layer is marked still and no animations run.
  • While Začínáme wants attention, the "?" draws nothing: the guide's layer stays hidden, the tour's bubble nudges, the status for assistive technology reads "Nejdřív dokončete Začínáme" / "Finish Getting started first", and focus stays on the "?".
  • Fork-like page. The page loads /.lazurio/shell.js and has <lazurio-rail>, <lazurio-column-head>, <lazurio-buddy> and a data-guide-help button, but no provideGuides. There, <lazurio-buddy> is defined, but after a click on the "?" it has no shadow root, no children and zero height.
  • Console. No errors other than the preview's three fake endpoints (/.lazurio/account/environments 404, /api/update/status 503, /api/content/jobs/latest 404), which answer the same way without this change.
  • Screenshots, 64 in all, are kept locally in the operator's drafts, for example cs-work-1440-1.png, cs-team-1440-2.png, en-team-700-2.png, cs-work-1440-0-busy.png and cs-work-fork-like.png.

Risks

• Interface v1 is permanent. Five names are added and none can be removed later.
• Fork impact. The next rollout defines <lazurio-buddy> in Chat and Automate, since both load the Launchpad's shell.js. With no provideGuides the element makes no shadow root and adds no listener; this was checked on a fork-like page in the browser.
• Collisions with open PRs. messages.ts and index.html may conflict with Launchpad Files: grid view with image previews, colour by file kind, shorter copy #357, Apps: add Work and Administration groups within Workspace #446 and Apps: an Organization's own tabs in Workspace (supersedes #446's per-browser groups) #467, and files-panel.ts with Launchpad Files: grid view with image previews, colour by file kind, shorter copy #357 (Files copy). Launchpad: the tour's gear stop for AI is its title alone #475 is untouched.
• Narrow screens. Below 768 px, the Files steps point into the folded column, so they show as a sheet with no ring. This is the failure mode the shaping accepted.

Open questions

• The English texts of the principles and of files-team were written by the agent. Matěj, please review the wording.
• Should "?" during Začínáme stay a nudge of the tour's bubble plus a status for assistive technology, or should it say something visible elsewhere? A visible card next to the tour's bubble meant two tours at once in the browser check.
• "Založte si Buddyho", at the end of the two Buddy principles, leads to the Dashboard's home until the Buddy sign-up page exists (task 994).

Refs: plan DEV-6612 (data/mission-control/plans/2026/09/DEV-6612-produkt-jedna.yaml), root decision 0180 addendum of 2026-10-18, #499.

🤖 Generated with Claude Code

Note

Add shell guide engine that explains pages in place via <lazurio-buddy>, starting with Files

• Adds a shell-owned guide engine (guide.ts) that plays one localized explanation at a time, rendered inside connected <lazurio-buddy> elements (elements.ts)
• Pages register explanations through the new provideGuides API; the Launchpad Files page supplies a Team-specific guide and a heading help button, and its former inline intro and shared-folder notes are removed in favor of the guide
• Includes bilingual principle content, a rendering layer with target rings and card placement (bottom sheet below 768px), a versioned message protocol with strict origin checks, and a busy reply when the onboarding tour owns attention; the tour now yields while a guide plays
• Adds test suites for guide content, protocol vectors, and page markup, plus the F56 decision record in decisions.md
• Risk: the Files page no longer renders its introductory and shared-folder paragraphs; any consumer of that copy or the removed shared method in files-panel.ts must be updated

^{Macroscope summarized 04b363b.}

[immakermatty]

Full suite on this exact head (04b363b, clean tree): bun test --timeout 30000 gave 4147 pass, 9 skip, 1 fail. The one failure is the known load flake #284 (wacli sign-in reads wacli.pid before the fake writes it), which passes 3/3 when its file runs alone; this PR does not touch wacli, src/tools or the server. The earlier full run, on the tree before the unused playGuide export was removed, gave 4148 pass, 9 skip, 0 fail. check:static and the focused suites (230/230) are green on this head.

[agentrozjedemeai]

@immakermatty — src/shell/guide.ts:263-271: Detaching the active clears playing without calling the layer’s draw(null, actions). Unlike withdrawal via provide(null), this leaves the layer’s document keydown/resize listeners and 250 ms interval running. On reattachment, the existing layer still considers itself visible; replaying the same explanation skips first-show setup (including focus and URL snapshot), so a later tick can close the new guide against the old URL. I reproduced the lifecycle on this exact head: attach → provide([]) → play("files") → detach produced only draw(show), no draw(null); reattach → play produced show, show. Close the active layer on detach and cover detach/reattach with a regression test before merge. Local: 151 focused tests pass, check:static passes; CI green; diff --check clean.

[agentrozjedemeai]

@immakermatty — Re-review of b1d6f22: the detach path now calls end("closed"), which clears the active layer through draw(null, actions), removes the layer listeners/timer, announces closed, and notifies attention listeners. The detach/reattach regression passes and the new behavior matches the prior finding; no remaining defect found in this fix. Local detached checkout: 152 focused tests passed, check:static passed, diff --check clean. Exact-head CI checks succeeded and unresolved review threads: 0. Approved for this head only.