refactor(web): onboarding goes back to upstream's three stages by Jacksondr5 · Pull Request #457 · Jacksondr5/j5code

Jacksondr5 · 2026-10-04T22:29:29Z

Hold: merges with the migration PR, which registers imported threads.

Problem

J5's welcome wizard has a fourth stage that gives each imported folder's conversations a Squadron. The plan in #412 retires Squadrons into projects, so onboarding goes back to upstream's three stages.

What changed

Sixth PR of the fold stack, on top of #456.

components/onboarding/WelcomeWizard.tsx is the upstream pin's file again, with two J5 edits kept:
- Branding: the app name and CLI command come from branding.ts, and the header shows the plain title in place of the T3 wordmark.
- "Providers": the second stage's label and its sentence ("We'll set up providers and projects on each"), where upstream says agents.
- Against the pin that is 11 lines added and 20 removed.
routes/welcome.tsx has been upstream's file since refactor(web): new-thread doors and drafts go back to upstream's projects #455.
Deleted: apps/web/src/j5/onboarding/ (the Squadrons stage, its logic and test, the import session hook) and j5/squadron/squadronClient.ts with its test, which has no caller left.
Left in j5/squadron/: SquadronDirectory (Fleet, the Inbox, the playbook author picker) and ThreadHomesClient (the sidebar's nesting rule).

Behavior note: going back from Projects resets the folder selection

Upstream keeps the selected folders in the Projects stage's own state. Leaving that stage (for example by clicking the Providers stage and continuing again) drops the selection and returns to the default recent folders.
J5's import session kept the selection across that navigation. It existed for the Squadrons stage and is deleted with it.
This PR follows upstream and adds no J5 code to keep the selection. It is a candidate to report upstream.

Why this PR is held

The wizard's import writes threads directly on the server (AgentSessionImporter), not through the launch command. So feat(squadrons): a thread launched without a Squadron joins its project's Squadron #430's rule, which puts a launched thread in its project's Squadron, does not cover imported conversations.
Without the Squadron stage, an imported conversation has no Squadron home. It is missing from Fleet, and an agent continued from one cannot message anyone.
On a fresh install the imported project has no Squadron at all, and since refactor(web): project creation, the sidebar filter and wording go back to upstream #456 a person cannot create one. join_squadron then has nothing to join.
The migration PR registers every thread, imported ones included. This PR merges with it.

UI changes

Captured by the tester on the base branch (#456) and on this PR, with the same data, viewport and theme.

Connect stage and the four-stage / three-stage step bar.

Before	After

Connect help shows J5 Code and the j5 pair / j5 serve commands.

Before	After

Provider setup stage.

Before	After

One scratch folder selected for import.

Before	After

Projects with no folders selected.

Before	After

After Projects: base opens Squadrons; head completes import and opens the project draft.

Before	After

Import completes into the selected project’s draft.

Before	After

First send from a new thread after import.

Before	After

Returning via the Providers stage: base keeps the chosen folder; upstream’s wizard restores its default selection.

Before	After

No discovered projects (simulated empty scan).

Before	After

Project scan waiting (simulated pending response).

Before	After

Project scan error with Retry (simulated scan failure).

Before	After

Stage navigation and the selection reset when returning to upstream’s wizard.

Before	After

Dark theme and 390px captures of the same states

Connect help shows J5 Code and the j5 pair / j5 serve commands. Dark theme.

Before	After

Connect help shows J5 Code and the j5 pair / j5 serve commands. Dark theme, narrow width.

Before	After

Connect help shows J5 Code and the j5 pair / j5 serve commands. Light theme, narrow width.

Before	After

Connect stage and the four-stage / three-stage step bar. Dark theme.

Before	After

Connect stage and the four-stage / three-stage step bar. Dark theme, narrow width.

Before	After

Connect stage and the four-stage / three-stage step bar. Light theme, narrow width.

Before	After

After Projects: base opens Squadrons; head completes import and opens the project draft. Dark theme.

Before	After

After Projects: base opens Squadrons; head completes import and opens the project draft. Dark theme, narrow width.

Before	After

After Projects: base opens Squadrons; head completes import and opens the project draft. Light theme, narrow width.

Before	After

First send from a new thread after import. Dark theme.

Before	After

First send from a new thread after import. Dark theme, narrow width.

Before	After

First send from a new thread after import. Light theme, narrow width.

Before	After

Import completes into the selected project’s draft. Dark theme.

Before	After

Import completes into the selected project’s draft. Dark theme, narrow width.

Before	After

Import completes into the selected project’s draft. Light theme, narrow width.

Before	After

Returning via the Providers stage: base keeps the chosen folder; upstream’s wizard restores its default selection. Dark theme.

Before	After

Returning via the Providers stage: base keeps the chosen folder; upstream’s wizard restores its default selection. Dark theme, narrow width.

Before	After

Returning via the Providers stage: base keeps the chosen folder; upstream’s wizard restores its default selection. Light theme, narrow width.

Before	After

No discovered projects (simulated empty scan). Dark theme.

Before	After

No discovered projects (simulated empty scan). Dark theme, narrow width.

Before	After

No discovered projects (simulated empty scan). Light theme, narrow width.

Before	After

Project scan error with Retry (simulated scan failure). Dark theme.

Before	After

Project scan error with Retry (simulated scan failure). Dark theme, narrow width.

Before	After

Project scan error with Retry (simulated scan failure). Light theme, narrow width.

Before	After

Project scan waiting (simulated pending response). Dark theme.

Before	After

Project scan waiting (simulated pending response). Dark theme, narrow width.

Before	After

Project scan waiting (simulated pending response). Light theme, narrow width.

Before	After

Projects with no folders selected. Dark theme.

Before	After

Projects with no folders selected. Dark theme, narrow width.

Before	After

Projects with no folders selected. Light theme, narrow width.

Before	After

One scratch folder selected for import. Dark theme.

Before	After

One scratch folder selected for import. Dark theme, narrow width.

Before	After

One scratch folder selected for import. Light theme, narrow width.

Before	After

Provider setup stage. Dark theme.

Before	After

Provider setup stage. Dark theme, narrow width.

Before	After

Provider setup stage. Light theme, narrow width.

Before	After

Limits of this evidence:

Simulated: the Projects stage's waiting, error and empty states were produced by intercepting the scan request in the browser.
Not tested: remote pairing, the desktop app and mobile.
Back navigation: the wizard has no Back button between Providers and Projects on either version. The browser's Back leaves the wizard on both, and Forward restarts it at Connect, losing the selection on both. The selection reset in the pair above is reached by clicking the Providers stage and continuing.
Confirmed live, and the reason for the hold: imported conversations stay unregistered, even after a first send in the project creates its Squadron.

Upstream impact

apps/web/src/components/onboarding/WelcomeWizard.tsx: FORK.md case 39 stays live for the four "Providers" wording edits, so the next upstream advance re-applies them; its Squadron-stage half is retired. The file-table row cites 39 and branding.
Register (docs/j5/product/upstream.md): D10 moves to the Retired section. The decision is Jackson's, in the plan for Retire Squadrons and fold their J5 behavior into projects (decided) #412.
The server's assignment route (ImportedThreadsHttp) stays, with no web caller; the migration PR removes it.

Checklist

One concern: the description has no "also"
Tests cover the changed behavior (backend changes ship with focused tests). The J5 onboarding logic and its test are deleted together; upstream's onboarding tests are untouched and pass.
UI changes: before/after screenshots above, and a video for motion or interaction
Upstream-owned files: each one is recorded in FORK.md (case text and file-table row) in this PR
Upstream product: any change to what upstream's product does has a human decision linked above and a register entry in docs/j5/product/upstream.md
Surfaces: entry points, clients, providers, contracts, reverse states, connection modes (see AGENTS.md)
Docs: definitions under docs/j5/product/ and user docs rewritten where this changes them. Feature definitions are left for the stack's docs PR, per the plan.

Surfaces walked

Entry points: the first-run redirect to /welcome, and visiting /welcome to reopen setup. Both render the same wizard.
Clients: web and desktop. Mobile has its own onboarding and is out of scope.
Providers: the provider stage is upstream's, relabelled only.
Contracts: unchanged. The assignment request and response types stay, unused by web.
Reverse states: reopening setup works as upstream's does. It no longer offers to give earlier imports a Squadron.
Connection modes: connection and pairing steps are upstream's.
Docs: FORK.md and the register, as above.

Verification

vp test run src/onboarding src/j5 in apps/web: 45 files, 376 tests pass.
tsc --noEmit in apps/web: no errors.
vp lint on src/components/onboarding and src/routes/welcome.tsx: no errors.
Live, by the tester: the first-run redirect; three stages; the app name and j5 pair / j5 serve in the pairing help; importing two real conversations into a selected project; landing in that project's draft; a first send from it; the import button disabled with nothing selected; skip; persistence across a reload.

Claude Opus 5.5 (1M context), Claude Code harness.

🤖 Generated with Claude Code

vercel · 2026-10-04T22:29:30Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
j5-code	Ready	Preview	Oct 8, 2026 4:28am UTC

bryantderosier

Reviewed this as part of the 454–457 stack. One merge prerequisite (already in the PR body, and nothing lower in the stack fixes it) plus a few docs/cleanup items. No security issues: this PR only removes client code, and POST /api/j5/squadrons/assign-imported is unchanged and still authenticated.

Hold: imported conversations never get a Squadron home. Onboarding import now finishes without assignImportedThreads. AgentSessionImporter emits thread.created directly with no J5 registration, FleetReadsHttp only lists registered placements, and SendService turns a missing home into A2ASenderNotJoinedError. So after onboarding, resuming an imported conversation leaves it out of Fleet, and its agent can't send_message or list_participants (normal user turns still work). Keep the merge hold until registration covers existing imports and future ones too. A one-time backfill alone leaves later imports uncovered. Please add focused import/registration coverage with that work.

Docs/cleanup:

FORK.md file-table row for WelcomeWizard.tsx credits only branding (B), but the file also has the "Agents" to "Providers" label edits, which are only recorded in case 39 (now retired). Record them in BRANDING.md or keep a live case.
docs/j5/product/features/squadron.md:22 still says each folder imported at onboarding gets a Squadron and mentions the first-Squadron gate. Both are false now, so the docs PR needs to cover it.
createSquadron, renameSquadron, deleteSquadron and assignImportedThreads in packages/client-runtime/src/j5/state.ts have no web or mobile caller at the top of the stack. They should go with the server route in the migration PR.

bryantderosier · 2026-10-06T12:11:35Z

        skippedThreadCount += threadImportResult.value.skippedCount;
        if (threadImportResult.value.importedCount > 0) {
-          memory.projectsWithImportedHistory.set(
+          projectsWithImportedHistoryRef.current.set(


Import finishes here without registering the imported conversations in the ledger, so resumed ones are missing from Fleet and their agents fail closed on send_message/list_participants. This is the documented merge hold; the follow-up needs to cover future imports as well as existing ones, not only a backfill.

I'm an AI agent (Claude) working for Jackson.

Agreed, and the hold stays. The description opens with it, and the PR is a draft so it cannot merge ahead of the migration PR. I've passed your two requirements to the Captain for that PR: registration has to cover future imports as well as existing ones, not only a one-time backfill, and it needs focused import and registration tests. The tester confirmed the gap live on this branch: imported conversations stay unregistered even after a first send creates the project's Squadron.

bryantderosier · 2026-10-06T12:11:35Z

 | `apps/web/src/hooks/useThreadActionMenu.ts`                                                                | A       | 21                                         |
 | `apps/web/src/routeTree.gen.ts`                                                                            | R       | generated route registrations for 6/9      |
-| `apps/web/src/components/onboarding/WelcomeWizard.tsx`                                                     | R       | 39, B                                      |
+| `apps/web/src/components/onboarding/WelcomeWizard.tsx`                                                     | R       | B                                          |


The Providers label edits aren't covered by B and are only recorded in case 39, which this PR retires. Please record them in BRANDING.md or keep a live case so the next upstream advance doesn't drop them.

I'm an AI agent (Claude) working for Jackson.

Fixed in the rebased head 288c0e6. I kept a live FORK.md case rather than using BRANDING.md, since this is wording and not identity: case 39 now leads with the four "Providers" edits in WelcomeWizard.tsx (the stage label, the Connect sentence and two comments), says to re-apply them on every upstream advance, and records its Squadron-stage half as retired. The file-table row cites 39 and B.

Jacksondr5 · 2026-10-06T15:09:47Z

I'm an AI agent (Claude) working for Jackson. Replies to the review points that have no inline thread:

docs/j5/product/features/squadron.md:22 still describes the onboarding Squadron and the first-Squadron gate. Agreed. Left alone here on purpose: this stack does not rewrite the feature definitions, and the Captain is carrying this to the docs PR.
createSquadron, renameSquadron, deleteSquadron and assignImportedThreads in packages/client-runtime/src/j5/state.ts have no caller. Agreed. Left on purpose: they go with the server routes and contracts in the migration PR, which this stack was told not to touch.

New head after the rebase: 288c0e6.

The welcome wizard loses its Squadron stage and imports into projects as upstream does. Branding and the Providers label stay. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

github-actions Bot added vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. size:XL 500-999 effective changed lines (test files excluded in mixed PRs). labels Oct 4, 2026

vercel Bot deployed to Preview October 4, 2026 22:30 View deployment

Jacksondr5 force-pushed the fold/onboarding-back-to-upstream branch from cc7cf2c to a8e8f88 Compare October 4, 2026 22:32

Jacksondr5 mentioned this pull request Oct 4, 2026

refactor(web): project creation, the sidebar filter and wording go back to upstream #456

Merged

6 of 7 tasks

vercel Bot deployed to Preview October 4, 2026 22:33 View deployment

Jacksondr5 force-pushed the fold/onboarding-back-to-upstream branch from a8e8f88 to 113e269 Compare October 4, 2026 22:37

vercel Bot deployed to Preview October 4, 2026 22:38 View deployment

github-actions Bot added size:XXL 1,000+ effective changed lines (test files excluded in mixed PRs). and removed size:XL 500-999 effective changed lines (test files excluded in mixed PRs). labels Oct 4, 2026

Jacksondr5 mentioned this pull request Oct 4, 2026

refactor(web): new-thread doors and drafts go back to upstream's projects #455

Merged

6 of 7 tasks

bryantderosier mentioned this pull request Oct 5, 2026

The J5 ledger keys on projects, and every thread has a home (migration 030) #459

Open

Jacksondr5 added this pull request to stack #471 October 5, 2026 19:53

bryantderosier reviewed Oct 6, 2026

View reviewed changes

Jacksondr5 force-pushed the fold/onboarding-back-to-upstream branch from 113e269 to baf76c9 Compare October 6, 2026 15:06

vercel Bot deployed to Preview October 6, 2026 15:07 View deployment

Jacksondr5 force-pushed the fold/onboarding-back-to-upstream branch from baf76c9 to 288c0e6 Compare October 6, 2026 15:09

vercel Bot deployed to Preview October 6, 2026 15:09 View deployment

This was referenced Oct 8, 2026

Check that Squadron is gone from code, docs and agent text (on or after 2026-10-28) #476

Open

Retire Squadrons and fold their J5 behavior into projects (decided) #412

Closed

Jacksondr5 force-pushed the fold/onboarding-back-to-upstream branch from 288c0e6 to 551ffeb Compare October 8, 2026 00:49

vercel Bot deployed to Preview October 8, 2026 00:50 View deployment

Jacksondr5 force-pushed the fold/onboarding-back-to-upstream branch from 551ffeb to 69e369c Compare October 8, 2026 01:33

vercel Bot deployed to Preview October 8, 2026 01:34 View deployment

Jacksondr5 force-pushed the fold/onboarding-back-to-upstream branch from fcca968 to ad1123e Compare October 8, 2026 02:33

vercel Bot deployed to Preview October 8, 2026 02:34 View deployment

Jacksondr5 force-pushed the fold/onboarding-back-to-upstream branch from ad1123e to 1912866 Compare October 8, 2026 03:34

vercel Bot deployed to Preview October 8, 2026 03:35 View deployment

Jacksondr5 mentioned this pull request Oct 8, 2026

feat(a2a): a thread's home is its project #482

Merged

5 of 7 tasks

refactor(web): onboarding goes back to upstream's three stages

197e79c

The welcome wizard loses its Squadron stage and imports into projects as upstream does. Branding and the Providers label stay. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Jacksondr5 force-pushed the fold/onboarding-back-to-upstream branch from 1912866 to 197e79c Compare October 8, 2026 04:27

vercel Bot deployed to Preview October 8, 2026 04:28 View deployment

Jacksondr5 closed this Oct 8, 2026

Jacksondr5 deleted the fold/onboarding-back-to-upstream branch October 8, 2026 04:28

Jacksondr5 restored the fold/onboarding-back-to-upstream branch October 8, 2026 04:29

Jacksondr5 reopened this Oct 8, 2026

Jacksondr5 marked this pull request as ready for review October 8, 2026 06:21

Jacksondr5 merged commit 79349ff into j5/main Oct 8, 2026
59 of 66 checks passed

Jacksondr5 deleted the fold/onboarding-back-to-upstream branch October 8, 2026 06:21

Navigation Menu

Repository navigation

refactor(web): onboarding goes back to upstream's three stages - #457

refactor(web): onboarding goes back to upstream's three stages#457
Jacksondr5 merged 1 commit into
j5/mainfrom
fold/onboarding-back-to-upstream

Jacksondr5 commented Oct 4, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Oct 4, 2026 •

edited

Loading

Uh oh!

bryantderosier left a comment

Uh oh!

bryantderosier Oct 6, 2026

Uh oh!

Jacksondr5 Oct 6, 2026

Uh oh!

bryantderosier Oct 6, 2026

Uh oh!

Jacksondr5 Oct 6, 2026

Uh oh!

Jacksondr5 commented Oct 6, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Jacksondr5 commented Oct 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

What changed

UI changes

Upstream impact

Checklist

Uh oh!

vercel Bot commented Oct 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bryantderosier left a comment

Choose a reason for hiding this comment

Uh oh!

bryantderosier Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

Jacksondr5 Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

bryantderosier Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

Jacksondr5 Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

Jacksondr5 commented Oct 6, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Jacksondr5 commented Oct 4, 2026 •

edited

Loading

vercel Bot commented Oct 4, 2026 •

edited

Loading