stablyai--orca/docs/reference/feature-discovery-interaction-tracking.md

Feature Discovery Interaction Tracking

This document defines local feature-interaction state used to decide whether Orca should still teach a feature with an education surface such as a tour or feature tip.

Decision

Track first meaningful interaction plus local interaction count for education-targeted features in PersistedUIState.featureInteractions.

Do not upload this state as broad analytics. Product analytics should continue to use bounded telemetry events and downstream product events. Local interaction state answers a different question: "Has this user already found enough of this feature that education would be redundant?"

Rules

• Add a FeatureInteractionId in src/shared/feature-interactions.ts before using it.
• Preserve firstInteractedAt, and increment interactionCount on each later meaningful interaction.
• Prefer explicit actions over passive visibility.
• Passive visibility is acceptable only when opening the surface is itself the product use, such as opening Tasks.
• Record after persisted UI is hydrated by using recordFeatureInteraction(...); it no-ops before hydration.
• Keep IDs stable. If the meaning changes materially, add a new ID.
• Do not include user text, paths, URLs, repo names, branch names, hostnames, commands, prompts, or tokens in this state.
• Old records without interactionCount hydrate as interactionCount: 1.

Feature Catalog

Feature	Interaction ID	Record when	Education use
Review notes to agent	review-notes	A diff or markdown review note is added, or review notes are marked sent to an agent.	Suppress or target a future review-notes tour/tip about adding line notes and sending focused feedback back to an agent.
AI commit generation	ai-commit-generation	AI commit-message generation is enabled or an AI commit message is generated.	Suppress future education about AI commit generation. No contextual tour is planned for this branch.
AI PR generation	ai-pr-generation	AI pull-request title/body/draft fields are generated.	Suppress future education about AI PR generation. No contextual tour is planned for this branch.
Floating Workspace	floating-workspace	The floating workspace opens, is enabled, or is configured.	Keep the existing Floating Workspace tour, and suppress future education about the global terminal/browser/markdown workspace.
Quick Commands	quick-commands	A terminal quick command is created or edited.	Suppress future tips about saved terminal commands. No contextual tour is planned for this branch.
Computer Use setup	computer-use-setup	Computer Use was selected in legacy onboarding, a permission setup is opened, or the skill setup terminal opens.	Suppress setup-focused tips once the user has started setup.
Computer Use	computer-use	A successful computer.* runtime method other than capability probing is handled.	Suppress future usage tips once an agent has actually invoked Computer Use.
Mobile pairing	mobile-pairing	Mobile is enabled or a mobile pairing QR/code is generated.	Suppress future mobile-pairing tips. No contextual tour is planned for this branch.
Browser element grab	browser-grab	Browser grab mode is started, an element is copied, or an element screenshot is copied.	Suppress future tips about grabbing page context once the user has used the element picker.
Browser annotations	browser-annotations	Browser annotation mode is started, an annotation is added, browser annotations are copied, or browser annotations are cleared.	Suppress future tips about annotating local pages and sending concrete UI feedback to an agent.
Cookie import	cookie-import	Browser cookies are imported from another browser or file, imported through runtime browser profile methods, or default imported cookies are cleared.	Suppress future cookie-import education without conflating cookie setup with Agent Browser Use itself.
Workspace board actions	workspace-board-actions	A card/status action, lane configuration, density change, pin drop, or board drag action is used.	Keep the existing workspace-board tour, and avoid repeating deeper board-action education after real use.
Automation creation	automation-created	A local automation or external Hermes cron is created.	Keep the existing Automations tour, and suppress creation-focused education after the user creates one.
Automation run	automation-run	A local or external automation run is manually queued.	Keep the existing Automations tour, and suppress run/inspection education after the user queues a run.
Resource Manager	resource-manager	The Resource Manager status-bar popover is opened, or its status-bar visibility is toggled in Appearance/status-bar controls.	Suppress future tips about CPU, memory, session, daemon, and workspace disk-scan controls after the user has found the manager.
Workspace cleanup / disk space	workspace-cleanup	The Space page opens, a workspace disk scan starts/cancels, or cleanup removes scanned workspace rows.	Suppress future tips about scanning workspace disk usage and reclaiming old workspace storage.
Ports	ports	The Ports popover opens, the Ports status-bar item is configured, external ports are expanded, or a port is opened/copied/stopped.	Suppress future tips about discovering and acting on workspace ports.
SSH	ssh	SSH status opens, SSH status-bar visibility changes, a target is added/imported/tested, or an SSH target is connected/disconnected.	Suppress future SSH setup/status tips after the user has interacted with remote target controls.
Provider usage tracking	usage-tracking	Stats & Usage is opened, Claude/Codex/OpenCode usage analytics are enabled, provider usage details are opened from the status bar, Gemini usage/OAuth is configured, or provider usage status-bar toggles are changed.	Suppress future tips about where to find token/rate-limit/usage tracking for Claude, Codex, Gemini, OpenCode, and related providers.
Claude account switching	claude-account-switching	A Claude managed account is added, selected, reauthenticated, removed, or selected from the status bar.	Suppress future tips about using multiple Claude accounts once the user has started account management.
Codex account switching	codex-account-switching	A Codex managed account is added, selected, reauthenticated, removed, or selected from the status bar.	Suppress future tips about Codex account switching and restart follow-up flows.
Workspace tabs	terminal-tabs	A workspace tab is created, reordered, renamed, recolored, pinned/unpinned, moved, or closed.	Suppress future tips about tab-level workspace organization. These are real workspace tabs, not workspace board cards.
Split panes	terminal-panes	A split group is created from the pane shortcut/menu, a split is resized, or panes are merged.	Suppress future tips about pane-level split workflows.
Tab splits	tab-splits	A workspace tab is moved into another pane or split into a new pane from a tab split/drop action.	Suppress future tips about tab-level split workflows separately from pane creation/resizing.
Agent Browser Use setup	agent-browser-setup	Browser Use was selected in legacy onboarding, enabled in settings, or its setup terminal opens.	Suppress future setup tips once the user has started Browser Use setup.
Agent Browser Use	agent-browser-use	A successful non-profile browser.* runtime method is handled.	Suppress future usage tips once an agent/runtime has actually driven Orca's browser.
Agent Orchestration setup	agent-orchestration-setup	Orchestration was selected in legacy onboarding, enabled in settings, or its setup terminal opens.	Suppress future setup tips once the user has started Orchestration setup.
Agent Orchestration	agent-orchestration	A successful orchestration.* runtime method is handled.	Suppress future usage tips once an agent/runtime has actually used orchestration.
Notifications	notifications	Notifications are enabled in onboarding/settings or a test notification is sent.	Suppress future notification setup tips.

Surface-Level Features

Orca also records surface-level interactions for feature areas where opening the surface is itself a meaningful discovery signal:

• workspace-board: workspace board opened
• workspace-agent-sessions: workspace terminal surface opened with agent split controls visible
• browser: non-blank browser page viewed
• tasks: Tasks page opened
• automations: Automations page opened
• floating-workspace: floating workspace opened
• workspace-creation: workspace creation flow opened

These remain intentionally separate from action-level IDs such as workspace-board-actions, automation-created, and automation-run. Surface-level IDs answer "has the user entered the feature area?" Action-level IDs answer "has the user performed the deeper workflow?"