feat(frontend): agentOS onboarding template and create flow behind feature flag

[NicholasKissel]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[NicholasKissel]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat(frontend): agentOS onboarding template and create flow behind feature flag #5135 👈 (View in Graphite)
• feat(frontend): redesign onboarding wizard #5116 : 1 other dependent PR (#5121 )
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[railway-app]

🚅 Deployed to the rivet-pr-5135 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
frontend-cloud	😴 Sleeping (View Logs)	Web	Jun 3, 2026 at 9:12 pm
ladle	✅ Success (View Logs)	Web	Jun 3, 2026 at 9:10 pm
website	😴 Sleeping (View Logs)	Web	Jun 3, 2026 at 9:08 pm
frontend-inspector	❌ Build Failed (View Logs)	Web	Jun 3, 2026 at 9:02 pm
mcp-hub	✅ Success (View Logs)	Web	Jun 3, 2026 at 9:02 pm
kitchen-sink	❌ Build Failed (View Logs)	Web	Jun 3, 2026 at 9:00 pm

[claude]

Review: agentOS Onboarding Template and Create Flow

The overall structure is solid - clean separation of the pure generator (build-agent-os-setup.ts) from the UI, consistent use of feature flags per CLAUDE.md, proper react-hook-form ownership throughout, and a useful Storybook harness. A few issues worth addressing before landing.

Medium severity issues:

1. Unverified sandbox providers generate potentially broken code. In catalog.ts, only docker has verified: true, but all 8 providers are rendered as selectable in SandboxMountStep with no warning. build-agent-os-setup.ts generates imports for unverified providers. The catalog JSDoc calls this out but the UI does not surface it to the user. Suggestion: either filter unverified providers out of the list or add a visual disclaimer (similar to the "Preview" badge already used elsewhere).

2. installCommand hardcodes npm while the rest of onboarding supports multiple package managers. In build-agent-os-setup.ts, the generated client always hardcodes npm install. The existing PackageManagerCode component supports npm/pnpm/yarn/bun. Worth threading a packageManager selection through AgentOsSelections or reusing the existing component.

3. ANTHROPIC_API_KEY hardcoded in generated client code. In build-agent-os-setup.ts, the generated client always uses ANTHROPIC_API_KEY. This is fine while Pi is the only available agent, but will not generalize when Codex, Amp, etc. ship. Consider adding an envKey field to AgentEntry.

Low severity issues:

4. create-agent-os modal renders without the feature flag guard. In both ns.$namespace.tsx and orgs.../ns.$namespace.tsx, the new CreateActorSheet variant="agent-os" block is mounted unconditionally. A user who navigates to ?modal=create-agent-os manually will see the sheet even with the flag off. Wrap with features.agentOs.

5. useWatch() with no arguments in StepHeading subscribes to all fields (const values = useWatch() as Record...). This re-renders the heading on every field change. Prefer passing specific field names to useWatch. Not a bug, but causes unnecessary renders.

6. resolveAgent fallback reaches AGENTS[0] which may not be available. If DEFAULT_AGENT is removed from the catalog, AGENTS[0] becomes the silent fallback. Throwing with a clear message would be safer.

Minor nits:

• Multiple useWatch calls in AgentOsHandoff - three separate subscriptions that could be combined into one.
• BuildTargetSelector mixes RHF render prop and direct setValue. Calling field.onChange instead is the idiomatic pattern.

Good catches:

• void navigate fix in actors-grid.tsx - correct since navigate returns a Promise.
• type="button" on BuildTargetCard and SelectCard - prevents accidental form submission.
• Feature flag agentOs: isEnabled("agent-os") with no platform guard matches the cross-flavor intent.
• Storybook harness in agent-os-onboarding.stories.tsx tests the selections-to-generated-code path cleanly.