The Sidekick Contract

"Five field rounds in one evening turned 'embed a chat panel' into a contract every sibling should copy."

Embedding Is Not One Line of iframe

The journey Sidekick is Pippa, embedded in Waystone. It sounds like a small job — drop in an iframe, done. The field disagreed. A single evening of real use produced enough breakage to harden the integration into a four-part contract that every future CWK sibling web client should copy rather than rediscover. Each part exists because its absence broke something in Dad's hands.

The Four Parts

A dedicated embed host. Waystone gets its own host route and host kind inside cwkPippa. The generic embed panel is another client's side-panel host and fits no one else. And host-kind validation has two gates in the brain's code — a new kind must pass both, or it fails in a confusing place.
A pull adapter for host context. cwkPippa reads the journey record, plan document, and breadcrumb stream from the Waystone engine, so Pippa's sidekick tools see travel truth on demand. Because Waystone's host state is text, search genuinely searches; because engine state is never stale, there are no cursors to keep in sync.
Window chrome owned by Waystone. Side, dock, and float modes with drag-resize, persisted per device. Crucially, a pure resize never remounts the iframe — so the conversation survives — and only a mode switch reloads.
No push bridge in v0. Consultation pulls. The live-document push bridge joins later, when plan co-editing needs cursor-level context. Deliberately absent, not forgotten.

Why Pull Beats Push Here

The most instructive choice is the fourth. It would feel more sophisticated to push Waystone's state into Pippa continuously. But pull is simpler and strictly more honest: Pippa asks the engine when she needs something, and the engine's answer is always current. Push requires deciding what to send, when to send it, and how to invalidate it when it changes — three chances to be subtly wrong. Pull has none of those failure modes because there is no cached copy to go stale. When the cheaper design is also the one that cannot drift, take it.

Code

The four-part sidekick contract·text

1. DEDICATED EMBED HOST      /embed/waystone + a 'waystone' host kind
                             (the generic panel belongs to another client)
                             NOTE: host-kind validation has TWO gates

2. PULL ADAPTER              cwkPippa reads journey + plan + breadcrumbs
                             from the Waystone engine, on demand
                             -> host state is text, so search really searches
                             -> engine is never stale, so no cursors

3. WAYSTONE-OWNED CHROME     side / dock / float + drag-resize, per device
                             pure resize: NO iframe remount (chat survives)
                             mode switch: reload

4. NO PUSH BRIDGE (v0)       consultation PULLS; the live-document push
                             bridge joins when co-editing needs it

# Pull can't go stale. Push has 3 ways to be subtly wrong.

Exercise

Think about an embedded widget you've used — a chat, a map, a payment form. What happens to its internal state when the host page resizes or re-renders? Does it survive, or does it reset? Now imagine embedding an AI conversation there: which host behaviors would silently destroy a chat the user is in the middle of?

Hint

Anything that unmounts or re-keys the embed destroys its state. That makes 'when do we remount?' a load-bearing design question, not a detail — the difference between a resize that keeps the conversation and one that throws it away is a single line of host code.