feat(voice): carry the app guide in session instructions

[dastratakos]

Why

The app guide — what Luke knows about himself — is ~16–18 KB of build-fixed prose, the same on every turn. It traveled as a conversation.item.create user message beside the four observed context kinds, which is the wrong vehicle for static content: each guide change deleted the old item and created a new one mid-conversation, moving the cached prefix and spending window the developer's own turns are evicted from. The Realtime session's instructions are the right home — a stable, cacheable prefix the service holds outside the conversation — so the guide now rides there, appended behind an [app guide] marker after the standing instruction head, which stays byte-identical as the prefix.

How

• realtimeInstructions() takes an optional guide text and appends it behind the marker; called bare (the mint, the connect-time sync) it is unchanged, so nothing new reaches the speak-only call or the introduction.
• New appGuideInstructionsEvents(guideText) in @sidecar/realtime builds one partial session.update carrying only the refreshed instructions — tools and audio are untouched, so the guide can never widen what a turn may do.
• RealtimeVoiceSession.updateGuide keeps the snapshot whole for validation and holds the rendered text pending; #flushContext sends the instructions refresh ahead of the context items, on the items' own economy: at the developer-opened turn that reads it, diffed by text, so an unchanged guide sends nothing and a mid-call guide change (settings, integration facts, update-row state) is a follow-up session.update at the next turn.
• The flush is gated by the same #carriesContext() check as the rosters, and speak() never flushes, so the speak-only announcement call stays guide-free exactly as it was context-free — it already received only the base instructions via the connect sync, and still does.
• APP_GUIDE is removed from CONTEXT_ITEM_KIND and the flush order; appGuideContextEvents is deleted rather than stubbed. Renderer AGENTS.md and the affected comments now describe the instructions carriage.

Tests

• The guide lands in session.update instructions on the developer call (standing head as prefix, guide behind the marker) and never as a [app guide] conversation item.
• A turn over an unchanged guide sends no further instructions update; a changed value sends exactly one carrying it.
• The speak-only call receives no guide on update or on an announcement readout (announcement is still item + response.create alone).
• Builder-level coverage: partial update (no tools), no response.create, blank text builds nothing.

Checks

./scripts/check.sh — exit 0: lint (biome + oxlint), typecheck, tests (2292 pass / 0 fail across the workspace), and builds all pass. ./scripts/verify.sh was not run because this environment is Linux; the change is portable (renderer/session logic and packages only, no macOS surface change).

🤖 Generated with Claude Code

Automated visual evidence

Download the deterministic macOS evidence · workflow run

• Commit: bd847ba5d2509b3312d4971b516055caf91f6084
• Scenario: smoke
• Physical-notch check: not performed by CI

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
luke-web	Ready	Preview	Aug 26, 2026 12:16am