onboarding
v0.2.0Guided console tour — step content, per-operator progress in state, and an injected page that spotlights the console element each step talks about.
Install
iii trigger compose::add worker=onboardingRun in your project with the iii engine running. Exact versions are immutable and digest-pinned.
onboarding
The guided console tour. The page and its tab are called learn-iii; a "tour" is one unit of content inside it, so a second tour can be added without renaming anything.
Three parts:
| Part | Lives in | Owns |
|---|---|---|
| Content | src/tours.mjs |
which tours exist, their steps, and the console element each step points at |
| Progress | the state worker, scope learn-iii |
how far each operator got, so a reload resumes mid-tour |
| Rendering | ui/page.tsx (injected into the console) |
the tour card, the spotlight box, and the page an older console falls back to |
Functions
learn-iii::tours::list— every tour in curriculum order.learn-iii::tours::get— one tour with all of its steps.learn-iii::progress::get— the status of every step per tour, with the observed event that closed it, plus the next tour to offer.learn-iii::steps::complete— mark one step complete. Passfired({ function_id, payload }) when an observed event closed it; the observed function and the event are kept as evidence. The first time a step closes, it is also announced on theonboarding:steps:completetopic (see Events).learn-iii::steps::reset— forget one tour and start it again.learn-iii::subscribe— add an email address to the iii product-update list (the last step's signup box; the POST happens here, never in the browser).
A step that waits on something carries a condition: an observe source the
page observes from the browser with a per-tab target. The agent-finished steps
observe state::on-changed with filters on input.scope (learn-iii) and
input.key (step_<id>_completed); the first step observes
harness::on-turn-completed and counts only turns of the tour's own chat. The
page also observes ade::workspace::on-changed to follow the layout, and
the worker serves its page through one ade::ui::asset observer per asset
({ kind: 'script' | 'style', path }).
host.iii.observe(
{
function_id: 'state::on-changed',
filters: { 'input.scope': { $eq: 'learn-iii' }, 'input.key': { $eq: 'step_reactivity_completed' } },
},
`learn-iii::condition::learn-iii::reactivity::${host.iii.browserId}`,
)Progress is written with state::update and its ordered atomic ops, never
state::get then state::set: two invocations can interleave around an
await, and a read-then-replace write would drop the earlier one. merge
walks and creates the path it names, so one step lands under its own tour.
A reset nulls its tour (the op set reaches top-level keys only for remove)
and the read drops nulls on the way out.
Events
Each closed step is published to the onboarding:steps:complete topic through the
queue worker, so anything that follows a tour subscribes to the topic and
never reads this worker's state. The payload:
{
"tour_id": "learn-iii",
"tour_title": "Find your way around",
"step_number": 3,
"step_id": "coder",
"step_title": "CODER"
}The step number is the 1-based position in the tour, read from the ordered step list. A step announces itself once per subject: a reload, or a second report from the agent, writes the same progress again but publishes nothing.
Delivery is durable. The worker publishes with iii::durable::publish, and a
subscriber observes queue::on-message with args
{ topic: 'onboarding:steps:complete' } under a stable observer id:
iii.observe(
{ function_id: 'queue::on-message', args: { topic: 'onboarding:steps:complete' } },
'my-worker::on-step',
{ id: 'my-worker::step-watch' },
)The queue worker keeps one durable queue per subscriber, keyed by its
observer id. A step waits in that queue until the subscriber takes it, and
a failed delivery is retried. A subscriber that restarts under the same
worker name and observer id within the engine's grace period takes its queue
back, with every step published while it was away; after that, the queue
keeps what it holds for the next observer with that id (see
Subscribing in the queue
worker's README). A subscriber that observes without an id gets a new
observer id, and with it a new, empty queue, each time it starts. The
engine's telemetry subscribes as iii-telemetry::onboarding-step-watch.
The publish itself is best effort: a project without the queue worker logs
the failure and still closes the step.