Files
PaperClipAI/maps/feature-map/onboarding.md
T
ce27dde855 Start onboarding in chat and defer execution until the user chooses work (#22077)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Onboarding connects an agent and gives the user a place to discuss
work.
> - The previous flow created an execution task and project before the
user chose a scope.
> - A standing chat can gather the goal and clear exit criteria first.
> - This pull request opens chat after onboarding and starts a live
welcome after the chat is visible.
> - The agent proposes work for acceptance, or creates a task when the
user explicitly requests one.
> - Subscription setup and shared question state must work for this
first conversation to succeed.

## Linked Issues or Issue Description

**Subsystem affected**
Company onboarding, agent chat, local subscription setup, task
numbering, and shared interaction views.

**Problem or motivation**
The first session creates work before the user has agreed to a goal.
Standing chats consume task numbers. An answered chat question can
remain pending in the inbox. Claude code entry requires an extra click,
and switching from Claude to Codex can leave an incompatible model
selected.

**Proposed solution**
Open an owner-bound chat for every new company. Start a live welcome
after the chat paints in a visible tab. Gather scope in conversation and
use the existing task acceptance flow. Keep chat records out of the task
number sequence. Publish question responses to shared caches and cancel
stale reads. Submit pasted Claude codes once and wait for verified
sign-in before connecting.

**Alternatives considered**
A fixed welcome would not use the onboarding context. A hidden execution
task would still create work and consume a task number. Keep the
existing task proposal and acceptance contract instead.

**Roadmap alignment**
This improves the shipped Agent Chat and Personal & Shared AI Accounts
flows in ROADMAP.md. It does not add a separate execution or approval
system.

Related prior work: Refs #19643 and #19512. Related route handoff work:
Refs #12557. This change replaces the automatic first task with chat; it
also repairs the subscription and shared question state paths used
during that journey.

## What Changed

- Finish onboarding in agent chat for default and team-template
companies. Create no execution task or project.
- Queue one live welcome after visible chat content paints. Pass company
goals and the initial idea as context. Preserve access, budget, and
hiring controls.
- Instruct the agent to gather a goal and exit criteria, offer an
interview, and propose tasks for acceptance. Allow direct creation on an
explicit user request.
- Leave new standing chats unnumbered. The first execution task receives
number 1. Preserve existing identifiers.
- Synchronize answered question cards across chat and inbox, including
concurrent requests and inactive cached views.
- Submit a pasted Claude authorization code once. Show connection
progress and hide the restart link while sign-in is still preparing.
Detect rejected OAuth codes promptly. Clear incompatible models when the
provider changes.
- Use `Work with [agent name]` as the default chat composer placeholder.
- Add regression coverage and update onboarding documentation and API
notes.

## Verification

- Completed a real Claude subscription journey on macOS with an isolated
local database. Authorized the account, pasted the real code, and
reached the review step without clicking Submit code or Connect. Get
started opened chat and the live welcome run succeeded. The company had
zero execution tasks, zero projects, and task counter 0.
- On rebased commit c664949858, 6 browser cases passed for
paste-to-connect-to-chat, task-free onboarding, existing-company
routing, the native connection probe gate, desktop/mobile planning, and
two-tab chat/inbox question synchronization.
- On the rebased head, 419 focused UI tests passed. The focused server
and adapter run passed 160 tests and hit one `socket hang up` in the
existing authenticated chat route test. The full 72-test conversation
suite passed on one repeat. The cause of that first socket failure
remains unconfirmed; the passing repeat does not establish its cause.
- UI typecheck and server declaration typecheck pass after the rebase.
The first server check found a missing local dependency from master; a
frozen-lockfile install repaired it. No dependency manifest or lockfile
change was needed.
- The first Greptile review found two welcome edge cases. Four new tests
reproduced both before the fix. On commit b380f14ef9, all 114 onboarding
and queue tests pass, including timeout retries and queued welcomes
replaced by a user message or chat reset. Server source and focused test
type checks pass on this revision.
- [Greptile
review](https://github.com/paperclipai/paperclip/pull/22077#issuecomment-6961533641)
gives rebased commit 2dbad34445 a score of
5/5. The current-head check passed. Both welcome review threads are
resolved, with no new actionable findings.
- CI serialized shard 8/9 found a missing OpenAPI inventory entry for
the new route file. The exact coverage test reproduced this locally.
Commit 17a72ec8b7 adds explicit mounted paths and documents both
board-only operations. All 65 OpenAPI and onboarding route tests and
server source typecheck pass after the fix. The final CI run passes on
this revision.
- Rebased onto master 23ce68a8dc and regenerated the SDK source registry
from committed inputs. Worktree preflight, SDK source validation, and
all 65 API/onboarding tests pass on final head
2dbad34445.
- On final head 2dbad34445, all 419
affected UI tests pass. UI package typecheck and server declaration
typecheck also pass. Commands: `pnpm --filter @paperclipai/ui
typecheck`; `node server/scripts/typecheck-layers.mjs
--declarations-only`; focused Vitest suites for the wizard, subscription
login, agent chat, shared interaction cache, and OpenAPI/onboarding
routes.
- [Final-head CI
run](https://github.com/paperclipai/paperclip/actions/runs/44208652564)
completed successfully on commit
2dbad34445. All required typecheck, build,
test, Runner, browser, serialized-server, and canary gates pass,
including the [final verify
job](https://github.com/paperclipai/paperclip/actions/runs/44208652564/job/134487749343).
The fresh routing gate selected the trusted AWS fleet after the
protected owner policy in #22098 merged. No source rebase was needed:
the gate reads that policy from protected master.
- The repaired OpenAPI shard passed in the earlier same-head CI run.
General server shard 8/12 hit a 20-second step timeout in the existing
`issue-recovery-live-run-agent-census` suite. This PR does not change
that suite or its fixture. All four tests pass locally on the exact
current commit in 84 seconds. The cause of the CI timeout remains
unconfirmed. Every other test job passed. A single failed-shard retry
was accepted but remained queued on its saved GitHub-hosted selection.
It was cancelled before test execution after #22098 merged. The fresh
full-CI run passed on the unchanged head under the approved AWS policy,
including [server shard
8/12](https://github.com/paperclipai/paperclip/actions/runs/44208652564/job/134481388730).
This passing execution does not establish the cause of the earlier
timeout.
- Worktree preflight, committed SDK source input validation, and diff
whitespace checks pass after the rebase.
- `pnpm verify` reports exit 2 because the new subsystem documentation
requires broader CI coverage. The final successful CI run supplies that
broader coverage. This is not a full local suite pass.

## Risks

- The initial task is now an explicit user decision. Existing onboarding
tasks and numbered records remain readable. No schema migration is
required.
- A welcome still depends on a working provider connection and the
normal run queue. Failed starts can be retried without duplicate
successful welcomes.
- Claude paste acceptance was verified with a real subscription on
macOS. This change does not claim a new live Codex or Windows acceptance
test.

## Model Used

OpenAI Codex, based on GPT-6, with tool-assisted reasoning, code
execution, terminal checks, and browser verification. The client does
not expose the exact routed build or context limit.

## 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: Scott Tong <scott@scottsmbpm5max.lan>
Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-17 16:52:35 -08:00

13 KiB
Raw Blame History

navigation
navigation
section sectionOrder order
Getting started and access 10 10

Onboarding and first work

An operator can start an instance, create a company, configure its first agent, and start in chat. Execution work begins after an accepted task proposal or an explicit task-creation request. Instance setup and company onboarding are separate steps.

Feature ID: onboarding.

Implementation: web wizard, CLI setup.

Agent access: companion.

Sub-features

  • instance: onboarding/instance — choose local instance configuration and start the server.

  • company: onboarding/company — create a company with its identity and initial agent.

  • adapter: onboarding/adapter — choose an available harness, model, account, and execution environment.

  • first-task: onboarding/first-task — leave setup in chat, clarify the goal and exit criteria, and accept or explicitly request the first task.

  • resume: onboarding/resume — return to an incomplete wizard without losing saved state.

The Cloud Product onboarding journey defines portal workspace creation, API-key connection, native Codex creation, and a first downloadable artifact with an independent oracle. Its dependent task-properties journey reuses onboarding state. This is a scripted coverage recipe, not a claim of a completed Cloud run or strict browser-only discovery.

How to get to it (user POV)

web-wizard

Open /onboarding or the onboarding launcher in an empty company context. Use /<company-prefix>/onboarding to resume an existing company's agent setup; the unprefixed route starts at organization naming on self-hosted instances. Cloud-managed instances reuse their existing company for agent setup.

First-agent onboarding offers only Claude and Codex, subject to instance adapter availability. Other providers remain available through Add agent after onboarding. A saved draft for another provider requires a new choice.

cli-setup

Use paperclipai onboard --help or paperclipai run --help to select an isolated data directory before setup.

Driving it with Playwright and the Paperclip CLI

Preconditions: follow the baseline. Use a new isolated data directory and record deployment mode. A configured adapter may still need account authentication.

web-wizard

Automated: wizard tests cover mocked wizard behavior; onboarding browser suite supplies its own test environment. Live model execution is a separate check.

  • Create company and resume. Start a fresh empty instance and run doctor using the verification skill. Run node .agents/skills/verify-paperclip/scripts/onboarding-smoke.mjs --evidence-dir "$VERIFY_EVIDENCE_DIR". The helper opens /onboarding in a fresh self-hosted instance, enters a unique name in e.g. Northwind Labs, and chooses Continue. The agent-name field must appear and the saved company must have no invented goal. Reopen the company-prefixed onboarding route and reload; the agent step must appear without creating another company. Screenshots and a trace capture the real UI action and result. This proves company creation/resumption, not hiring or a first model run.

Manual: Create a disposable company and first agent. Leave midway, reopen the company's onboarding route, and finish; drafts save automatically. Follow the agent chat, verify the selected agent and company, and watch the live welcome. No execution tasks or projects should exist yet. Request an interview or describe a goal and clear exit criteria, then accept the suggested task. Verify one standalone task is created. Reload chat and ensure the welcome is not repeated. Also verify an explicit task-creation request uses the normal handoff directly. See chat-first onboarding. Legacy first-task asset evaluations cover existing task-based onboarding, not this chat landing.

For Codex or Claude, choose the harness to prove automatic first-agent runner selection. On a qualified target it saves Paperclip Runner. The wizard has no runner dropdown or empty Advanced section. Do not switch runners after onboarding when claiming proof of that default. Test the selected runtime and account, then complete a bounded useful task and follow-up with an independently checked file artifact. Saved execution configuration and recorded run identity must match after reload. The Codex first-task eval applies operator QA bounds before Get started through the existing agent configuration API. It verifies that only timeout and concurrency change; automatic runner, account and environment choices remain. These campaign bounds are separate from production creation defaults. Use runner validation and environment qualification for the prerequisites; a successful login alone is insufficient.

For managed Cloud setup, an outdated default Claude CLI is prepared automatically in a private versioned runtime directory before its hello test. Verify that the selected model and account stay unchanged and that the compatible executable is actually used. A failed installation still blocks hiring. Cloud failures must not display Manual debug shell commands or legacy operator hints; self-hosted failures retain that help. Wizard controls and runtime controls cover these boundaries. They do not establish live Cloud onboarding success.

For a new Claude agent on an explicit immutable sandbox image or a Daytona named snapshot, use Connect to qualify the selected environment through the existing permission-gated probe. Do not preprobe outside onboarding when claiming this first-use path. Fresh scoped discovery determines the runner for both the account test and hire; the measured Legacy result remains valid. An instance-admin denial, incomplete cleanup, missing lease or changed configuration stops setup before the adapter test or hire. Daytona resolves the selected snapshot to its immutable provider ID before creating the measured lease; native execution pins that same ID. Mutable image tags and other providers’ named templates remain unqualified. Helper controls and mounted wizard/new-agent tests use mocks; live managed acceptance remains a separate gate. For a new Codex agent with Auto on a saved immutable OCI sandbox, Connect first uses the existing saved environment probe when authoritative qualification is absent. The board actor needs the existing instance-environment administration permission. Refresh company/environment-scoped discovery before testing the selected runtime. A denied probe, unconfirmed cleanup or setup failure must be visible and retryable through setup. Creation and discovery themselves allocate no target. A valid measured unsupported target follows the server's Legacy default. Named Cloud snapshots remain a separate unqualified boot-identity and fresh-signup gap.

Selected native setup derives its target isolation as task execution does. The hello probe retains its read-only permission profile, approval-never policy and bounded provider turn. It skips Codex's project-instruction discovery in its new, empty private workspace; ordinary tasks still load their project instructions. Local and SSH transports retain Codex isolation. An injected environment flag cannot establish an outer sandbox identity. Verify these boundaries with the existing native setup controls and a real managed task/follow-up; source checks alone are insufficient.

The explicit manual Product E2E cell confirmation-replies.runner-codex.daytona.task-card-accept covers this fresh managed wizard path without fixture agent creation or a fixture preprobe. Its existing attachment oracle checks a downloaded physical file and follow-up continuity. Setup evidence must correlate both lease IDs with the same company, environment and provider; missing responses or unmatched rows keep cost coverage unknown. Run this cell only on an eligible target with separately authorized provider, runtime and cleanup reservations. Its source and mock controls are prepared. The literal ea6c8eb5e16d61111968f633a66748b397b64a3e live attempt failed: the child document existed, but the physical file was attached to the parent, and recovery stopped the completion callback before a provider turn. The failed report remains evidence; the revised source still needs live proof. Local cases and automatic selection remain unchanged.

For accepted file-producing work, verify exactly one self-assigned child with a self-contained description. The onboarding run must yield through the existing dependency/block disposition so the child's own execution can publish its file. Native file registration remains bound to the executing task. On completion, the original conversation must receive the actual child and downloadable file links. Document-only child work may finish inline. Interview execution proposals must start their selected work after acceptance; a saved plan alone is not the requested result. Only an explicitly plan-only request stops at planning. Existing first-task asset controls check the instructions, not model compliance. Inspect the child's execution, document, downloaded file and source-correlated completion reply in the real journey.

Leave and resume during harness/runner setup. Confirm the draft retains the explicit choice and compatible account bindings, old native Codex setup links recover the harness and runner, and a changed harness or runner invalidates stale test results. Existing Legacy agents remain Legacy when their onboarding/setup configuration is reopened; this journey does not migrate them.

Reload both /onboarding and the company-prefixed route after the first agent is saved but before Get started. The authorized draft must retain its current step and that agent's execution choice. An explicit new-company opening still starts fresh. Opening another company must clear the previous company's resource IDs; an unauthorized account must not restore its draft. Existing component controls cover these boundaries; they do not substitute for the managed first-task eval. The existing mocked-login browser case reopens and reloads Connect directly. It checks the saved company/name/harness/runner, exact active authorization session, one login start and no hire while login is pending. This is login UI evidence, not a provider or managed-environment qualification.

cli-setup

Automated: CLI onboarding and isolated test drive cover their setup contracts; they do not establish that every model account is usable.

Manual: Run setup in the disposable directory, open the URL it prints, and confirm the instance identity and company. Restart using that same configuration and verify saved state. Exercise an unavailable adapter and confirm an actionable error.

Gotchas

  • An empty company, an empty instance, and an unauthenticated browser are different states.
  • Creating an agent does not prove its provider login or first execution succeeded.
  • See access for authenticated deployments and agents for later hiring.

Storybook verification

resume

Capability ID: onboarding/resume.

Scope: ui Storybook: Restored incomplete wizard; invalid or unauthorized saved company; temporarily withheld draft; account switch; storage failure. Production: Reload company-prefixed onboarding without duplicating company; restore only authorized account/company draft and retain input after recoverable loading failure. Sources: Source: OnboardingWizard.tsx, onboarding-state.ts. Tests: OnboardingWizard.test.tsx, onboarding-state.test.ts, onboarding.spec.ts

instance

Capability ID: onboarding/instance.

Scope: cli Storybook: No authored UI story required for host installation and startup. Production: Configure isolated data directory, start instance, confirm printed URL/identity/health, restart with saved configuration. Sources: Source: onboard.ts, onboard-service.ts. Tests: onboard.test.ts, onboard-service.test.ts, test-drive.test.ts

Documentation scope: Login, invitations, and access

Deployment modes and core login/invite/member/token paths are mapped; exhaustive identity-provider, expiry, role, and resource-policy combinations remain.