2 Commits

Include renames

Author	SHA1	Message	Date
TonioandClaude Opus 5	3d366ba15f	Rebuild the onboarding agent arc on the prototype's step design (#11905) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The onboarding wizard in `ui/` hires that first agent. It runs three steps: create the agent, connect a model, and review > - A standalone prototype holds the agreed design for these steps. #10786 ported that prototype, but #11067 reverted it in full because the port deleted `OnboardingWizard.tsx` while four pull requests were editing that file > - Those four pull requests have since merged. The revert said the port can "re-land incrementally", and this is that re-land > - This pull request takes the presentational layer from the prototype only. It keeps master's wizard as the source of behaviour, so the eight onboarding fixes merged since the revert stay in place > - The benefit is that the three agent steps match the agreed design, and no merged fix is lost to get there ## Linked Issues or Issue Description Refs #10786 — the first attempt to land this design. Refs #11067 — the revert that asked for it to re-land in smaller steps. No public issue exists for the re-land. The problem is described below. **Subsystem affected** The `ui` package. The change touches the onboarding wizard, the agent capsule, and one Storybook story. It adds four small presentational components under `ui/src/components/onboarding/`. **Current behavior** The wizard's agent steps do not match the prototype. Each step shows a small heading beside an icon, above a form. The agent capsule sits below that heading and does not animate. The agent gets a name but no role, so every first agent is created as `ceo`. The wizard also shows a five-segment progress bar on these steps. A walker who enters on the agent step cannot reach the first two segments, so two of the five can never be filled. **Proposed behavior** The three steps use the prototype's card, its centred display heading, and its footer. One capsule sits above the heading and stays mounted across all three steps, so it reads as one object being built rather than three screens that each show their own. A three-segment strip counts these steps for a walker who enters on them. The full-length bar stays for a walker who starts at step one, so that count never restarts partway. The agent step gains a role. The options come from the agent role enum, not from the prototype's mock list. **Reason and benefit** The design is agreed and already built once. Re-landing it presentation-first keeps the behaviour that master gained after the revert. Sourcing roles from the enum matters. The prototype offers "Coder", which is not a valid role — the enum uses `engineer` — so a walker who picked it would fail validation at hire time. **Breaking changes** None. The wizard keeps its routes, its draft format, and its hire call. The draft gains one optional field, `agentRole`. A draft saved before this change loads without it and falls back to the default. ## What Changed - Add `ui/src/components/onboarding/`: `Stepper`, `OnboardingCard`, `OnboardingHeading`, `FooterNav`, `AgentPreview`, and shared motion constants - Rebuild wizard steps 3–5 on those parts: one card, the capsule above a centred heading, and one footer - Hold one `AgentCapsule` across the three steps. It springs in once, then morphs from dashed slot to traced outline to filled - Add `strokeDraw` to `AgentCapsule`. It traces the outline instead of cross-fading it. The dashed layer holds until the trace ends - Add a role select to the agent step. Choosing a role fills the name, unless the walker typed one - Show one progress indicator per run, not two - Label strip segments by destination, not by number - Add `motion` to the `ui` package - Add a Storybook story for the strip and the capsule states ## Verification Run the tests: ``` pnpm --filter @paperclipai/ui exec vitest run pnpm --filter @paperclipai/ui exec tsc -p tsconfig.json --noEmit ``` 4235 tests pass. The typecheck is clean. To see the steps, start the app and open `/<PREFIX>/onboarding` for a company that has a company-level goal. The wizard opens on the agent step. Step three requires a hire. Three absence assertions were checked by fault injection. Each one fails when the old behaviour returns: - put the step counter back, and the "shows no step counter" test fails - default `strokeDraw` to true, and the cross-fade test fails - restore the timer gate on the strip, and the indicator test fails ## Risks Low to medium. `motion` is one new dependency in `ui`. #11067 gave dependency weight as one of three reasons to revert #10786, so this branch carries the smallest set that works. `motion` drives the step transitions and the capsule choreography, and three files import it. An earlier revision of this branch also added `three` and `@types/three`. Both are removed. They existed for the 3D backdrop, which belongs to the auth and welcome screens rather than to these three steps, so nothing on this branch imported them. The role select changes what the wizard sends. Before this change every first agent was hired as `ceo`. Now the walker chooses. The values come from the enum, so the server accepts all of them. Steps 1 and 2 keep the older design. They do not run on the Cloud-first path, where the company already exists. ## Model Used Claude Opus 5 (`claude-opus-5`), with extended thinking, tool use, and code execution. Used for the code, the tests, and this description. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-21 16:41:53 -07:00
3 people	6f9801a46b	feat(ui): NUX rework behind enableConferenceRoomChat experimental flag — capsule onboarding, conference-room chat, unified composer (#8000) ... ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The first-run experience (onboarding wizard) and the chat surfaces (conference-room/board chat, task threads, composers) are the product's front door — they decide whether a new operator understands "hire agents, give them work, review results" in the first five minutes > - Today those surfaces feel ticket-y and form-like: the wizard is a static multi-step form that ends in an anticlimactic "Launch" screen, the task composer and board chat behave differently from each other, and agent-feed issue quicklooks misbehave (multiple flyouts open at once, cards jump on hover) > - We wanted to iterate toward a conversational, team-centric NUX — but without risking the workflows of everyone already running Paperclip > - This PR reworks the NUX behind a new default-OFF `enableConferenceRoomChat` experimental flag: a capsule-motif onboarding wizard that builds your team as you answer, a conference-room chat surface, one shared ChatComposer across surfaces, brand-accurate status chips, and feed-quicklook fixes — with the pre-existing UI fork-and-frozen as `*Classic` components that flag-OFF users keep > - The benefit is a complete, testable modern NUX that anyone can opt into from Settings → Experimental, with zero default behavior change and a clean path to either graduate or drop the experiment ## Linked Issues or Issue Description No pre-existing GitHub issue — feature description per `feature_request.yml`: - **Problem / motivation:** Paperclip's onboarding wizard and chat surfaces grew up as separate ticket-centric forms. New users get a form-filling experience rather than the feeling of standing up a team; the board chat and task threads use different composers with different affordances; the agent feed's issue quicklook can stack multiple popovers and shifts cards on hover. - **Proposed solution:** A coherent NUX experiment behind one experimental flag (`enableConferenceRoomChat`, Settings → Experimental, default OFF): capsule onboarding wizard with an evolving team capsule, conference-room chat, unified `ChatComposer`, team-centric copy, brand status chips, quicklook single-flight fix. Flag-OFF users get the exact pre-experiment UI via frozen `*Classic` forks, verified by an on/off parity test matrix. - **Alternatives considered:** (a) incremental unflagged restyling — rejected: the changes interlock across surfaces and would drip risk into every release; (b) a separate app shell / route for the new NUX — rejected: too much divergence, the flag + classic-fork pattern keeps the diff reviewable and reversible. - **Roadmap alignment:** `ROADMAP.md` lists **CEO Chat** ("a lighter-weight way to talk to leadership agents... should still resolve to real work objects"). This experiment is groundwork in that direction (conference-room chat resolves to issues/tasks via the same composer used in task threads) and does not change the core task-and-comments model. Related PRs found in the dedup search (same area, none duplicate this work — they target the classic wizard, which this PR intentionally leaves intact and mergeable): - #5385 — Coach-driven onboarding: conversational entry + agent-companies package import - #5378 — Onboarding wizard: reusable adapter picker + probe card - #6636 — ui(onboarding): friendly error surface + retry for the wizard - #7005 — fix(onboarding): explicitly await first-task wake - #2616 — fix: restore workspace directory config in onboarding wizard ## What Changed - **Experimental flag plumbing** — `enableConferenceRoomChat` in shared types/validators, server instance-settings service + API, Settings → Experimental card with explicit enable/disable copy - **Onboarding wizard** — classic wizard forked and frozen (`OnboardingWizardClassic`); flag-ON variant is a 5-step capsule wizard with a persistent evolving `AgentCapsule` (gradient/glow motif), team-centric reframed copy, and a typing-dots intro (hardened with fake-timer tests) - **Conference-room chat** — flag-ON board-chat surface with agent bubble name/icon headers and copy/vote/timestamp action rows (`AgentBubbleActionRow`) - **Unified composer** — shared `ChatComposer` adopted across surfaces; translucent surface + scroll-mask removal; "Agent mode"/"Plan mode" relabels; no-assignee confirmation `AlertDialog` (new `ui/alert-dialog.tsx` primitive); `@task` reference picker + linkification in mentions - **Agent feed** — single-flight issue-quicklook store (one popover at a time), flyouts open to the left, removed hover translate-y jitter - **Status chips** — brand-accurate task status chips behind the flag (light/dark, 1px borders per paperclip.ing/brand) - **Tests** — flag on/off parity matrix across IssueDetail, NewIssueDialog, Sidebar, wizard, gate components; component tests for all new pieces - **Merge with `master`** — one conflict in `ui/src/components/IssueChatThread.tsx`, resolved by keeping master's new `AssigneeChip`/`HandoffWakeRow`/`RunStatusBadge` components inside the flag-gated metadata-row chrome (details in commit `21a5642a`); post-merge fixes: vitest 4 mock typing in `MarkdownEditor.test.tsx`, flag hook made safe for provider-less mounts (master's new isolated component tests) - **Branch hygiene** — internal design wireframes/mockups stripped before the PR (they live in the Paperclip issue threads) - No user-facing documentation changes required: the flag is intentionally experimental and self-described in the Settings card; no existing docs reference the affected surfaces ## Verification - `pnpm run typecheck` — green across the workspace (ui, server, shared, plugins) - Full UI suite (`vitest run` in `ui/`, clean worktree at this HEAD): **1593/1595 passing, 223/224 files** — the 2 remaining failures are in `src/components/artifacts/ArtifactCard.test.tsx` and **fail identically on pristine `origin/master`** (pre-existing upstream, unrelated to this branch) - Full server suite (`vitest run` in `server/`, same clean worktree): results in PR checks; flag plumbing covered by instance-settings tests - Targeted post-merge resolution check: `IssueChatThread`, `IssueChatThreadSystemNotice`, `IssueDetail`, `Sidebar`, `ConferenceRoomChatGate`, `OnboardingWizardVariant`, `NewIssueDialog`, `InstanceExperimentalSettings`, `MarkdownEditor` — 172/172 passing - Manual walkthrough: flag OFF (default) → onboarding wizard, task thread, board chat, composer all render the classic UI; flag ON via Settings → Experimental → capsule wizard, conference-room chat, unified composer, status chips active - Screenshots: see below **Flag on/off screenshots** (committed on this branch under `screenshots/PR-8000-*`): | Surface | Flag OFF (classic, default) | Flag ON (experimental) | | --- | --- | --- | | Settings → Experimental |  |  | | Task thread |  |  | | Home / nav |  |  | | Conference Room (flag-ON only surface) | — |  | Capsule onboarding wizard walkthrough screenshots (flag ON) are attached to the Paperclip design/implementation threads; the wizard requires a fresh instance so it is captured via the e2e harness (`tests/e2e/nux-phase4-screenshots.spec.ts`). ## Risks - **Large surface, but gated:** all new behavior sits behind `enableConferenceRoomChat`, default OFF; flag-OFF rendering is locked by frozen `*Classic` forks plus an on/off parity test suite - **Classic forks are frozen at the fork point (`e3aada1d`):** master features added to the live thread component after that point (assignee handoff chips, run status badge, composer mention coach) render in the flag-ON path; the flag-OFF task thread keeps the fork-point behavior until the experiment graduates (forks deleted) or is dropped (forks restored as canonical). Called out for reviewer attention. - **Merge-conflict resolution in `IssueChatThread.tsx`** (commit `21a5642a`) deserves reviewer eyes: master's new handoff/run-status components were kept; the base toast-style no-assignee flow remains replaced by the AlertDialog flow introduced on this branch - Schema/server changes are additive (one optional boolean instance setting); no migrations of existing data ## Model Used - Claude (Anthropic) via Claude Code running in the Paperclip agent harness (agent: ClaudeCoder) - Branch implemented across multiple agent sessions on Claude Opus-class models with extended thinking + tool use (file edits, shell, Playwright screenshots); merge/PR session model ID as reported by the harness: `claude-fable-5` (Claude Code CLI) - All code was agent-authored and board-reviewed through Paperclip issue threads (plans, wireframes, confirmations) before merging ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes (none required — experimental flag, self-documenting Settings card; noted above) - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green (run 3 on `8af3041a`: all 16 gates SUCCESS, incl. e2e and all 4 serialized-suite shards) - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups (re-review verdict: Confidence 5/5, “Safe to merge”; all 4 round-1 findings fixed + confirmed resolved; both summary notes addressed in `8af3041a`) - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>	2026-06-11 16:32:55 -05:00