app-glossary - SKILL.md Agent Skill

name: app-glossary description: Use when defining or clarifying project-specific terms — callLLM, AI Context Block, anon_id, Async Reflection, Vapi, Soniox (STT), Cartesia Sonic (TTS), session_log, screen_contexts, useScreenContext / useLLM / useRealtimeVoice / useVoicePlayer / useAsyncReflection, VoiceContext, distinct_id, InputMethodContext, lib/analytics.ts, logEvent, track, Stage 5, Founding User Message, Hard Gate, Direct LLM Path, Mic Persistence, Voice-Driven Navigation, Anonymization Architecture user-invocable: false

Glossary

Source: Google Sheet Guided Growth OS App Master · tab Glossary · gid 1901215804 · contributors: anyone (add as needed).

41 definitions for every technical term used across the workbook. Land here when any term in another tab is unfamiliar.

When to use

Encounter an unfamiliar acronym, hook name, table name, or pattern name.
Need a precise definition for an architecture concept (caught-up principle, state delta, etc.).
Disambiguating similar terms (e.g. track() vs logEvent(), Cartesia Sonic 3.5 vs Cartesia Sonic API).

Terms

Term	Definition	Where It Appears
AI Context	Structured block of info about a screen the LLM reads on every call. Tells the LLM what screen the user is on, what state the app is in, what behavior is expected. Stored in the AI Context Block column of the Screens tab.	Screens tab, Architecture tab
AI Context Block	The Column D content from the original Voice Journey Sheet (now the AI Context Block column of the Screens tab). One block per screen. Contains SCREEN, STATE, BEHAVIOR, DO NOT, NEXT.	Screens tab
Autocapture (PostHog)	PostHog feature that automatically captures every button click (with the button text), every link click, every form submission, every page view, every page leave. Enabled by default after running the PostHog Wizard.	PostHog Events tab
`callLLM()`	The single backend wrapper function for every LLM call in the app. Fetches context + delta, prepends to base prompt, routes to Cartesia or direct LLM, returns response. Provider-agnostic. NEW in v6.0.	Architecture tab, Tasks P1-34
Vapi	Voice orchestration platform that handles real-time STT-LLM-TTS for live voice conversations. Used in MVP for onboarding (Path 1) and feedback sessions. Pluggable STT/TTS providers — we use Soniox (STT) and Cartesia Sonic 3.5 (TTS) through Vapi. Replaces Cartesia Line (May 5 2026 pivot — Cartesia Line concurrency limits at scale).	Architecture, Tasks (P1-12, P1-13, P1-15, P1-16)
Cartesia Sonic 3.5	Cartesia's TTS engine. Used for the cloned voice ("Yair Amsel 4 (enhanced)"). Real-time generation. Code's literal `model_id` is `sonic-3` today; locked target `sonic-3.5`.	MP3 Files, Architecture
Soniox	The STT primitive (not a Cartesia product). Real-time speech-to-text, multilingual auto-detect, sub-200ms. Sole STT across all paths — replaces the retired Cartesia Ink and evaluation-era Deepgram. Realtime via `soniox-stream.ts` (WebSocket); batch via `/api/stt`.	Architecture
Cartesia Ink (retired)	Cartesia's former STT engine. Replaced by Soniox; no new consumers.	Architecture (historical)
`checkin_type`	PostHog event property indicating which check-in fired the event. Values: `morning` \| `evening` \| `ad_hoc`.	PostHog Events
Direct LLM Path	Non-voice path for LLM calls. Frontend → `/api/llm` → backend → `callLLM()` → LLM. Used for text input, tap-driven habit creation, journal parsing, settings, insights, summaries. Cheaper than Cartesia (no voice minutes burned).	Architecture, Tasks P1-38
`distinct_id` (PostHog)	PostHog's unique ID per user. Before signup it's an anonymous ID generated by PostHog. After signup our auth handler calls `posthog.identify(supabaseUserId)` which merges anonymous activity with the identified user.	PostHog Events, Architecture
`input_method` (PostHog property)	PostHog event property tracking whether a user action was done via `voice` or `manual` (typing/tapping). Set globally via React's `InputMethodContext`, read by every `track()` call. Lets us measure voice vs manual usage of every feature.	PostHog Events
`InputMethodContext`	React context defined in `src/contexts/InputMethodContext.tsx`. Tracks whether the user is currently using voice or manual input. Read by `track()` calls throughout the app to set the `input_method` property automatically.	PostHog Plan v5 Step 4
`lib/analytics.ts`	Single file in the codebase that talks to PostHog. Every other component imports `track()`, `identifyUser()`, `setUserProperty()`, `resetAnalytics()` from this file. Never import PostHog directly in a component.	PostHog Plan v5 §1.2
`logEvent()`	Frontend utility that writes to `session_log` via `POST /api/session_log`. Called on every meaningful user action. NEW in v6.0. Distinct from PostHog's `track()` — `logEvent` feeds the LLM state delta, `track()` feeds product analytics.	Architecture, Tasks P1-40
LLM-Centric Architecture	v6.0 correction: the LLM is the brain of the entire app, not just voice. Every interaction (voice, text, taps, background) eventually goes through the LLM. AI context is for the LLM, not the voice agent specifically.	Architecture
Mic Persistence	UX-02: Once mic is granted and ON, it stays listening throughout an active voice session. User never re-taps mic to continue speaking.	UX Rules (UX-02)
MP3-only Screen	A screen that plays a pre-recorded MP3 (no live LLM call). In MVP, used for: VOICE-CAP. In Phase 2: the 28 SUB-* subcategory response screens. Frontend calls `useVoicePlayer` hook.	Screens
PostHog	Product analytics platform. Records events like signup, check-in completion, voice usage. Used to build funnels, retention reports, and dashboards. Free tier + $50K startup credits cover MVP.	PostHog Events, Architecture
PostHog Wizard	AI-powered CLI tool (`npx @posthog/wizard`) that auto-installs PostHog SDK, configures it, enables autocapture + session replay + error tracking, creates 10-15 custom events from codebase, installs PostHog MCP server. Run once at start of PostHog implementation.	PostHog Plan v5 Step 1
`screen_contexts` (table)	Supabase table that stores AI Context Blocks at runtime. Seeded by `scripts/voice-sync/seed_contexts.py` from this Sheet. Read by `/api/context` endpoint. NEW in v6.0.	Architecture, Tasks P1-31
Screen Type	Classification of a screen: Silent (no voice), MP3-only (pre-recorded only), LLM-active (calls LLM), Hybrid (some voice, some silent).	Screens
`seed_contexts.py`	Python script that reads the AI Context Block column from the Sheet and upserts to Supabase `screen_contexts` table. Re-run any time the Sheet is edited. NEW in v6.0.	Architecture, Tasks P1-31
`session_log` (table)	Append-only Supabase table that records every meaningful user action. Source of state delta for LLM context. NEW in v6.0. Distinct from PostHog (different consumer).	Architecture, session_log Events, Tasks P1-32
Session Replay (PostHog)	PostHog feature that records user sessions so you can watch how users navigate the app. 5,000 free replays/month. Mask sensitive inputs via `maskAllInputs` setting.	PostHog Plan v5 §8.1
State Delta	The list of recent events (from `session_log`) that gets prepended to every LLM call. Tells the LLM what's happened since it last spoke. Dynamic — rebuilt per call. NEW in v6.0.	Architecture, session_log Events
`track()` (PostHog)	Function in `lib/analytics.ts`. Calls `posthog.capture(event, properties)`. Used to fire all custom PostHog events. Distinct from `logEvent()` which feeds `session_log`.	PostHog Plan v5 Step 3
`useScreenContext`	Frontend React hook that tracks the current screen and fetches its AI context block. Replaces ad-hoc context handling. NEW in v6.0.	Tasks P1-41
`useLLM`	Frontend React hook for direct LLM calls (non-voice path). Calls `/api/llm` which uses `callLLM()` backend-side. NEW in v6.0.	Tasks P1-41
`useRealtimeVoice`	Frontend React hook for Vapi voice sessions. Opens connection via Vapi Web SDK to deployed Vapi assistant. Streams mic audio, plays response audio, surfaces live transcript, handles interruptions. Used by onboarding screens and free-form voice conversations.	Tasks P1-16
`useVoicePlayer`	Frontend React hook for pre-recorded MP3 playback. Used for Async Reflection prompts/acks/closings on check-in screens, the VOICE-CAP message, and Phase 2 subcategory/category/milestone MP3s. Plays from Supabase Storage. No LLM involvement — pure playback.	Tasks; Async Reflection state machine
`useVoiceSession` (PostHog)	Frontend React hook in `src/hooks/useVoiceSession.ts`. Wraps mic interactions with analytics tracking. Fires `start_voice_session`, `complete_voice_session`, `cancel_voice_session` events. Sets `InputMethodContext` to `voice` during session.	PostHog Plan v5 Step 6
`VoiceContext`	React context provider that prevents conflicts between MP3 playback and real-time voice. Tracks `voiceMode` (idle/mp3/realtime) and (NEW v6.0) `cartesiaSessionActive`.	Tasks P1-11, P1-39
Voice-Driven Navigation	UX-03: In voice mode, user never taps a button to advance. The conversation IS the navigation. Agent calls `navigate_next` when step complete.	UX Rules (UX-03)
Hard Gate	QA tests that MUST pass before launch. P1-43 (AI Context Cross-Channel) is the Phase 1 hard gate.	Tasks
Founding User Message	Special coaching moment delivered at `ONBOARD-BEGINNER-10`. "As one of the first 50 people to use Guided Growth..." Emotional peak before entering app.	Screens (ONBOARD-BEGINNER-10)
LLM Provider	Currently OpenAI (`gpt-4o-mini`). Can be swapped to Gemini Flash or other providers. `callLLM()` abstracts the provider so the rest of the app doesn't care.	Architecture
Async Reflection	v2 plan check-in pattern. NOT Vapi. Flow: pre-recorded MP3 prompt (Yair voice) → user voice via Soniox STT → brief MP3 'thinking' ack → LLM-generated personalized response streamed to Cartesia Sonic API for live TTS in cloned voice. State machine: PROMPT → LISTENING → THINKING → RESPONDING → FOLLOWUP_OPTIONAL → CLOSING → DONE. Used by all 9 check-in screens (MCHECK-01/02, ECHECK-01..06). Cost target ~$0.006/check-in.	Architecture, LLM Activation, Screens (MCHECK/ECHECK), Tasks P2-29
`anon_id`	Random hash assigned to each user at signup. Separate from their Supabase auth user_id. ALL behavioral data (check-ins, habits, journal entries, session_log, PostHog events, LLM context) keyed to `anon_id`. Identity (email, name) lives in `user_profiles` keyed to auth user_id. The `anon_id` is what gets passed to `callLLM()`, never the auth user_id.	Architecture, LLM Activation, Tasks P1-46
Anonymization Architecture	v2 plan privacy decision. Even our team can't directly link a row of behavioral data back to a person without going through the anon_id mapping. User-facing message: GC-16. Implementation: P1-46 (Stage 1, ~3 hours). Pairs with future support tokens (FF-09, post-MVP) for support troubleshooting.	Architecture, GC-16, Asana FF-08/09/10
Cartesia Sonic API	Cartesia's TTS-only HTTP API endpoint. Used by Async Reflection (check-ins) and Direct LLM voice path (free-form voice convos). Cheaper per minute than orchestrated voice (Vapi) because there's no orchestration — we just send text and get audio back. Different from Cartesia Sonic 3.5 which is the underlying TTS engine.	Architecture, LLM Activation
Stage 5	v2 plan MVP execution stage covering check-ins, free-form voice conversation, and text chat. Includes: Async Reflection state machine (P2-29), ~30 MP3s VA-generated (P2-30, reduced from 65 for MVP), feedback sessions via Vapi (P2-31), text chat GPT-4o mini (P2-32), wiring HOME screens (P2-33) + MCHECK/ECHECK screens (P2-34), Yair tone bible (P2-36). All five MVP plan stages: Stage 1 Foundation, Stage 2 callLLM wrapper + integrations, Stage 3 Onboarding LLM-active screens, Stage 4 QA + safety + polish, Stage 5 check-ins + text chat + feedback.	Tasks (Stage column), Screens (Stage column)

Refresh

mcp__google-sheets__get_sheet_data(
  spreadsheet_id="1iNEdUm5vqmjk3YGEF1uMwfurcvgVRHykWUeBGHDBqcw",
  sheet="Glossary"
)

Trigger: "refresh app-glossary" or "resync the sheet".

Last refreshed: 2026-05-11