[Silthus]

Problem

Feature flags. workflows-first-run gates the first-run experience. Shared template/schema fixes remain unconditional; sandbox and reach integrations are separate follow-ups.

First-run engagement events need to describe the actions in the onboarding journey.

Depends on #112076. GitHub shows the cumulative diff against master. Incremental range: e4c0685e1290..614229051e5f.

Warning

Merge risk: medium. The default-off first-run flag gates engagement controls. Only project admins can turn on the project setting.

Fork handoff for source #112088. Modernized head 614229051e5f92a35923a45a13f9d4c79c4ef5df. This draft prepares review and recreation in the upstream repository.

Changes

Kind	Files	Lines
Production	8	+232 −2
Tests	2	+155 −6
Total	10	+387 −8

• Authors can choose to capture workflow email engagement events during customization.
• An admin can enable engagement events from the sending banner.

Historical screenshot from the original head. It does not verify the modernized head.

|

|

|

|

How did you test this code?

Final freshness proof: the nine core layers descend from b75567aca6cce9f0499e882463fc7e71d65a064c. The template API suite passed 31 cases; frontend first-run, sender, welcome, setup-task and test-send suites passed 110 cases across 16 suites. Full frontend TypeScript and all nine strict increment gates passed with no new Semgrep findings. API types were regenerated from the current backend source in the owning layers; the final full OpenAPI run produced zero drift. The default-off workflows-first-run gate remains, and sandbox/reach follow-ups are excluded. Historical screenshots and reviews retain their recorded scope. Fresh upstream CI, a new browser render and a fresh Claude review remain unchecked.

The independent cumulative frontend run passed 106 tests across 15 existing suites. Backend metadata/API suites passed 31 tests. OpenAPI regeneration completed successfully. Final frontend typecheck and strict cumulative preflight passed with zero failures. Storybook has not produced a usable rendered screenshot on the new head. Historical images and proof remain preserved below.

Test rationale: Existing engagement and customization tests cover admin permissions, flag-off updates, creation ordering and saved engagement settings.

Historical proof on 4d2d7f1, before modernization on 2026-10-07

Test seams: firstRunMakeItYoursLogic (the switch and the create) and firstRunEngagementEventsLogic (the banner action). The API is mocked at the HTTP layer. The tests assert the team PATCH the frontend sends.

Test rationale:

• firstRunMakeItYoursLogic.test.ts: three new cases and one extended. They catch an on switch that never turns the setting on, an update sent before the create or with more than one field, an update for an off switch or a member, and an update after a rejected create. The closest existing test, the create case, asserts only the workflow payload.
• firstRunEngagementEventsLogic.test.ts: one case and one it.each. They catch a banner action that sends more than the one field, that stays offered once the setting is on, or that a member can trigger.
• Stories: MemberAccess on Make it yours and SendingAsMember on the banner. The existing TwoEmails and Sending stories now show the admin state.

Red before the change, green after

Red, the new Make it yours tests on the parent tree:

✕ creates a active workflow with every edited email, the sender and the matched event
✕ creates a draft workflow with every edited email, the sender and the matched event
✕ turns the setting on with one update of only that field, after the workflow is created
✕ leaves the setting off when the switch is off
✕ shows a member the switch off and disabled with a reason, and sends no update
Tests:       5 failed, 10 passed, 15 total

The banner action tests went red with the admin and setting guard removed: both rows of the it.each failed.

Green on the final tree: every suite in products/workflows/frontend/firstRun/, none skipped.

Local gate on the final tree: jest on products/workflows/frontend/firstRun/, pnpm --filter=@posthog/frontend typescript:check, oxlint and oxfmt --check on the touched files, and the pre-push hogli ci:preflight --strict. No Python, serializer or enum changes, so no ruff or hogli build:openapi.

Not checked: the running app. The screenshots come from the committed Storybook stories in a headless browser. Fork CI runs need approval.

Historical references: link 1, link 2, link 3, link 4, link 5, link 6, link 7, link 8, link 9.

Release status

Fork handoff only. This task does not activate rollout flags. Upstream CI and the unavailable Opus review remain handoff gaps.

• This change is behind a feature flag and is not available to users

The first-run journey uses the existing default-off workflows-first-run flag. Core uses verified own-domain senders and the baseline single-step test-send endpoint. Core has no sandbox, testing-v2 or email-reach dependency. No flag rollout is part of this modernization.

Docs update

None. The flag is off, and no doc under docs/ covers the first run.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Agent: Claude Code, Claude Opus 5.5 (claude-opus-5-5); Codex, GPT-6.1 Sol for the 2026-10-07 modernization.

Skills: modernize-pr, pr, writing-pr-descriptions, writing-voice, unslop, merge-risk, running-ci-preflight, and tdd for behavior adaptations.

This freshness replay preserves each published snapshot increment on pinned upstream b75567aca6cce9f0499e882463fc7e71d65a064c. Historical reviews remain scoped to their original heads. The parent-coordinated Claude Opus 5.5 review attempt hit an API rate limit; the modernization review remains incomplete. No real SES delivery, DNS changes or flag rollout occurred.

Final freshness replay: T3 Code, Codex, GPT-6.1 Sol (gpt-6.1-sol). Skills: pr, writing-pr-descriptions, writing-voice, unslop, stacking-prs, running-ci-preflight. Fork drafts remain unready; no preview label or rollout flag was activated.