feat: emit posthog-next-steps.md alongside the setup report

[ethangui]

Problem

Closes #447.

The wizard finishes a successful run by emitting posthog-setup-report.md — a manifest of what changed. That works as a record but leaves a real gap between "wizard finished" and "PostHog is integrated and merged." Closing that gap requires the developer (or their coding agent) to discover several things independently — most of which the wizard already knows at run time:

• That production builds may need re-running to catch lint / type issues from generated code.
• Which env var names were just added (so they can be mirrored in .env.example, monorepo bootstrap scripts, etc.).
• That a $ai_generation smoke-test is useful when LLM analytics is queued — and irrelevant on a Django / Rails / Swift / Android / etc. integration that doesn't have an LLM call site.
• That a "returning visitor" path can bypass the auth-handler-only identify call, leaving session events on anonymous distinct ids.

Encoding that as a deterministic handoff turns "90% done" into "one prompt away from done" for any agent picking up the work.

Changes

posthog-next-steps.md — the handoff doc

Adds a deterministic markdown file alongside the agent-written posthog-setup-report.md. Where the report describes WHAT changed, the new file describes what still needs to happen — verification steps, known SDK quirks (currently empty per integration; see "open questions"), and project glue the wizard intentionally never touches.

The doc adapts to the run:

Section	Condition
Run unit tests — wizard-rewritten or wizard-instrumented call sites may need updated mocks	JS/TS integrations
LLM smoke-test ($ai_generation) — strategy-agnostic, points the reader at the setup report for specifics	additionalFeatureQueue contains AdditionalFeature.LLM
Source-maps glue	Browser-bundle integrations only (nextjs, nuxt, vue, react-router, tanstack-*, angular, astro, sveltekit, javascript_web)
Env var names in glue section, with singular / plural / empty-fallback prose	Pulled from config.environment.getEnvVars(), never hardcoded

A Django, Rails, Swift, Android, etc. user no longer gets a handoff doc telling them to grep for @anthropic-ai/sdk.

The agent prompt itself — please review the wording

This PR introduces a single canned prompt the user copies into their coding agent. The exact text is up for review — it's the handoff's load-bearing UX, and the wizard team should have final say on tone, length, and instructions:

Read posthog-setup-report.md and posthog-next-steps.md. Verify each item in the "Verify before merging" checklist. Apply any fixes for items that fail. Update the project glue listed in this file if it applies. Open a PR with the changes plus a summary of what was verified.

Built by buildCodingAgentPrompt(reportFile: string) in src/lib/workflows/posthog-integration/handoff.ts. Single paragraph (no embedded newlines, so triple-click selects cleanly). If you want different wording, that one function is the only place to change it.

setPostExitMessage / getPostExitMessage — the agent-prompt surface

The handoff doc deliberately does not embed the prompt. An earlier iteration did, and the obvious problem surfaced quickly: a prompt instructing the agent to "Read posthog-setup-report.md and posthog-next-steps.md" embedded inside posthog-next-steps.md is a circular reference — the agent re-tokenizes the same prompt every time it re-reads the file.

So the prompt is sourced separately, wrapped in a horizontal-rule frame (buildCopyPasteBlock), and surfaced through a new workflow-agnostic accessor pair:

// src/lib/post-exit-message.ts
export function setPostExitMessage(session: WizardSession, message: string): void
export function getPostExitMessage(session: WizardSession): string | undefined

posthog-integration's postRun calls setPostExitMessage after a successful handoff write. start-tui.ts's cleanup reads via getPostExitMessage and writes to stdout AFTER releaseTerminal() — so the message lands in the user's normal scrollback (where they can triple-click it for copy) regardless of which exit path the wizard takes (tui.unmount, KeepSkillsScreen.tsx's direct process.exit, error paths).

What the user sees in their terminal after ✔ PostHog integration complete:

──────────────────────────────────────────────────────────────────────────────
Copy this into your coding agent (triple-click to select):
──────────────────────────────────────────────────────────────────────────────

Read `posthog-setup-report.md` and `posthog-next-steps.md`. Verify each item in the "Verify before merging" checklist. Apply any fixes for items that fail. Update the project glue listed in this file if it applies. Open a PR with the changes plus a summary of what was verified.

──────────────────────────────────────────────────────────────────────────────

The horizontal rules and header sit at column 0; the prompt body is on its own line surrounded by blanks so triple-click selects only the prompt.

Why a side channel and not OutroData.postExitMessage

I tried OutroData.postExitMessage first. It silently failed end-to-end. Diagnostic instrumentation in cleanup confirmed the cause:

• nanostores' setKey shallow-spreads the top-level session object, so frameworkContext (nested) is shared by reference across atom replacements, but outroData (top-level) is not.
• agent-runner.ts captures a session reference at the start of runAgent, then near the end runs session.outroData = config.buildOutroData(...). By that point, every pushStatus / setOutroDismissed / etc. during the agent run has replaced the atom session many times. The mutation goes to a stranded object the atom no longer references.
• ink-ui.outro reads this.store.session.outroData (current atom view, undefined) and falls back to {kind, message: stripAnsi(config.successMessage)}. Every other field — reportFile, changes, postExitMessage — is silently dropped on the floor.

This is a wizard-architectural bug that already affects reportFile today (which is why the Check ./posthog-setup-report.md for details exit-line suffix doesn't render — the team's existing partial workaround in ink-ui.outro covers message only). Worth a follow-up wizard-level fix that has agent-runner.ts push outroData through store.setOutroData(...) rather than direct mutation.

For this PR I worked around it via frameworkContext-as-side-channel. Same mechanism the existing getNextStepsHandoff / setNextStepsHandoff and DASHBOARD_DEEP_LINK_KEY accessors use, just generalized to any workflow that wants to surface persistent post-exit text.

Implementation map

• src/lib/post-exit-message.ts (new) — workflow-agnostic accessor pair (setPostExitMessage / getPostExitMessage) on frameworkContext. Includes a docblock explaining the staleness rationale so a future contributor doesn't "simplify" it back to outroData.
• src/lib/workflows/posthog-integration/handoff.ts (new) — pure helpers: buildNextStepsMarkdown(ctx), writeNextStepsFile(installDir, ctx), buildCodingAgentPrompt(reportFile), buildCopyPasteBlock(prompt), plus handoff-status accessors (getNextStepsHandoff / setNextStepsHandoff) and the outro-bullet helper buildHandoffBullet(status). writeNextStepsFile returns a discriminated union { ok: true; path } | { ok: false; error } matching the existing wizard-tools.ts convention.
• postRun in posthog-integration/index.ts — calls the writer with the actual integration enum value, the actual env var names from config.environment.getEnvVars(), and session.additionalFeatureQueue.includes(AdditionalFeature.LLM). Stashes the handoff result via setNextStepsHandoff, then on success stashes the framed prompt via setPostExitMessage. On failure: getUI().log.warn(...) + analytics.wizardCapture('next steps file write failed', ...).
• buildOutroData — renders either Wrote posthog-next-steps.md ... or Could NOT write posthog-next-steps.md (...) in the changes list. (Note: this bullet is itself silently dropped due to the same stale-session bug above; it'll show up in the OutroScreen once the wizard team fixes that.)
• bin.ts + src/ui/tui/start-tui.ts — cleanup reads getPostExitMessage(store.session) and writes to stdout after releaseTerminal(). Workflow-agnostic surface; any future workflow can opt in.
• OutroData.postExitMessage was removed. Advertising a field that the wizard's own session-mutation pattern silently drops is worse than not advertising it.

Type design

NextStepsContext.integration is the Integration enum (not a loose string), and KNOWN_QUIRKS_BY_INTEGRATION is Record<Integration, string[]> and exhaustive — adding a new Integration member requires declaring its quirks list (an empty array is fine and explicit). Mirrors the FRAMEWORK_REGISTRY pattern in src/lib/registry.ts.

writeNextStepsFile's return type, getNextStepsHandoff's read, and the ink-ui.outro-style fallback all use the same discriminated-union shape, narrowed via runtime type guards. The accessor pairs centralize the unsafe frameworkContext cast behind one runtime check per type, mirroring getAuditChecks in audit/types.ts.

Known limitations / open questions

• Wizard architectural follow-up: agent-runner.ts session.outroData = X direct mutation drops fields silently due to nanostores' setKey replacing the top-level session. The right fix is wizard-level — push outroData through store.setOutroData(...) (probably accept OutroData as a second arg to getUI().outro(message, data) so the call site doesn't need store access). Out of scope for this PR; happy to follow up if the team wants.
• Agent prompt overlap with the agent-written report: agent-prompt.ts:35-38 still tells the skill agent to write "any manual steps the user should take next" into posthog-setup-report.md. With the handoff doc those steps are now duplicative. Touching the shared skill prompt would also affect audit, agent-skill, and revenue-analytics — left for the team to decide direction.
• No quirks pre-filled. All entries in KNOWN_QUIRKS_BY_INTEGRATION are empty arrays today. An earlier iteration registered an @posthog/ai messages.stream(...) quirk for JS+LLM runs, but a real end-to-end wizard run revealed the wizard sometimes uses OpenTelemetry auto-instrumentation rather than the wrapper, where that quirk does not apply. I dropped the registration to avoid shipping wrong advice for half of all installs. The team is the right owner to register strategy-agnostic quirks when they emerge.
• Surfacing the agent prompt in-TUI is intentionally out of scope. setPostExitMessage solves the persistent-scrollback need at the smallest blast radius. Rendering it inside OutroScreen and/or hooking up a [c] clipboard copy hotkey would be nicer UX but adds a clipboard dep + cross-platform handling and crosses workflow → TUI boundaries the team should design intentionally.

Test plan

pnpm typecheck — clean.
pnpm lint — 0 errors (warnings unchanged from main).
pnpm jest — 36 suites, 624 passed / 3 pre-existing skips.

Two new test files:

• src/lib/workflows/posthog-integration/__tests__/handoff.test.ts — 25 cases covering markdown rendering, conditional content (LLM/JS/source-maps), env-var-name passthrough (singular/plural/empty), buildCopyPasteBlock shape, buildCodingAgentPrompt parameter behavior, accessor pair, file-write happy + failure paths, and a "handoff doc does NOT embed the agent prompt" regression catch.
• src/lib/__tests__/post-exit-message.test.ts — 4 cases covering round-trip, missing-key returns undefined, type-guard rejects non-string values, and a "survives shallow setKey clones of the top-level session" test that pins the exact bug we hit. A future "simplification" back to outroData will fail in CI with a comment explaining why.

100% line coverage of handoff.ts and post-exit-message.ts.

Beyond unit tests:

1. I drove posthogIntegrationConfig.run().postRun() + .buildOutroData() directly against a fresh git clone of a real Next.js project (/tmp/flashy-fresh-wizard-test) with mocked credentials — exercises every code path end-to-end except the LLM agent loop. All 16 content checks pass.

2. Then I ran the actual wizard end-to-end via node dist/bin.js against the same fresh clone (real OAuth, real agent run, real PostHog project — full ~$5 / ~12 min loop). The handoff doc, the success bullet, and the post-exit prompt block all appeared as designed. The end-to-end run also surfaced two bugs that drove changes in this PR: the OTel-vs-wrapper LLM-analytics non-determinism (motivated dropping wrapper-specific content from the handoff) and the stale-session bug above (motivated the side-channel mechanism).

Edge cases I considered but did not test:

• Empty installDir: path resolution is upstream; sess.installDir is always a real string by the time postRun fires.
• Markdown special chars in frameworkName: sourced from config.metadata.name (a wizard-internal constant), not user input — a test would lock in an arbitrary escaping policy that doesn't currently exist.
• Very long quirk lists: quirks are a hand-curated internal const, not external input.

LLM context

This PR was co-authored with Claude Code (Opus 4.7). Multiple rounds of multi-agent code review ran across the working tree before this body was finalized — five specialist reviewers (general code, test coverage, comment / docstring review, silent-failure hunt, type design) plus a codex review second-opinion pass per round. Concrete things each round caught:

• Round 1. KNOWN_QUIRKS_BY_INTEGRATION keyed by skill IDs ('nextjs-app-router') but the runtime label is the Integration enum ('nextjs'); the map never matched in production. Tightened to Record<Integration, string[]> exhaustive over the enum. Handoff content over-fitted to JS+Anthropic; conditional sections gated on JS-ness + LLM-queued. Outro lied on write failure (changes-list bullet was unconditional). Hardcoded NEXT_PUBLIC_* env names. No telemetry on failure path.
• Round 2. NEXT_STEPS_FILE constant dropped from imports during a refactor, leaving a hardcoded string in the warn line that could diverge from buildHandoffBullet. Type-design recommended exporting NextStepsHandoffStatus and adding a getNextStepsHandoff / setNextStepsHandoff accessor pair (mirroring getAuditChecks precedent). Silent-failure-hunter recommended a runtime type-guard for the frameworkContext read so a future shape drift is caught at runtime instead of producing garbage.
• Round 3. Cross-read against a real wizard run revealed the LLM-quirks section assumed the @posthog/ai PostHogAnthropic wrapper — but the wizard chose OpenTelemetry auto-instrumentation that run. Strategy-agnostic refactor.
• Round 4. Circular-reference critique on the embedded "Hand this to your coding agent" section. Moved the prompt out of the doc.
• Round 5 (this round). Real wizard runs surfaced that the OutroData.postExitMessage field was silently dropped end-to-end. Diagnostic instrumentation in cleanup confirmed the stale-session bug. Pivoted to the workflow-agnostic setPostExitMessage / getPostExitMessage side-channel. Trimmed duplicated rationale in three places, narrowed buildCodingAgentPrompt to (reportFile: string), exported POST_EXIT_MESSAGE_KEY so the test stops hardcoding the literal.

I read the PostHog CONTRIBUTING.md and AI policy before submitting; the PR template structure here matches .github/pull_request_template.md. Test coverage is unit + a deep integration script + a real wizard end-to-end run; full details in the test plan above.

[gewenyu99]

Hey! This is a great idea :D

There's a few things I'm gonna ask you to do to get this merged:

• I think this PR should go mostly in the PostHog/context-mill repo as a resource.
• I think this should be part of the same report, we can have this next steps as a check list at the bottom.
• I would let the model pick out relevant items to plop into the report.

I have some more comments on the actual content, but I'll defer the review there.

Please remember to @PostHog/team-docs-wizard for review! We sometimes miss these PRs.

Thanks for doing this!

[ethangui]

Thanks @gewenyu99, agreed — much more elegant to keep the content in context-mill. Turns out the report template (incl. ## Next steps) already lives there in llm-prompts/basic-integration/1.3-conclude.md, so the checklist + "let the model pick relevant items" is basically a one-file edit, no wizard code. I'll move it there and drop the deterministic TS approach.

One open question: the original PR also printed a copy-paste prompt to the terminal after exit ("read the report, verify the checklist, open a PR"). That can't move to context-mill — terminal output is wizard-side. My preference is to keep a simple one-liner handoff there so the operator can paste it straight into their coding agent — feels like the piece that turns "report written" into "one prompt from done." What do you think?

[gewenyu99]

@ethangui Agreed. I think that can stay in this PR. A custom handoff screen is a good idea

[ethangui]

Closing this in favor of two focused PRs that implement the approach we settled on in review — thanks @gewenyu99 for the steer.

After your feedback the change drifted substantially from what's here: the verification content moved into context-mill, and the wizard side slimmed to just surfacing the handoff. Rather than force-push a wholesale rewrite over this thread, it's cleaner to split it:

• context-mill (the checklist content): feat: add a "Verify before merging" checklist to the integration report context-mill#174
• wizard (the handoff surface): feat: surface a coding-agent handoff prompt on wizard exit #595

Both reference #447, which stays open until they land and context-mill releases. Review continues on those two PRs (cc @PostHog/team-docs-wizard).