mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-18 23:08:26 +01:00
## 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 commit2dbad34445a 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 master23ce68a8dcand regenerated the SDK source registry from committed inputs. Worktree preflight, SDK source validation, and all 65 API/onboarding tests pass on final head2dbad34445. - On final head2dbad34445, 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 commit2dbad34445. 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>
208 lines
13 KiB
Markdown
208 lines
13 KiB
Markdown
---
|
||
navigation: {"section":"Getting started and access","sectionOrder":10,"order":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](../../ui/src/components/OnboardingWizard.tsx), [CLI setup](../../cli/src/commands/onboard.ts).
|
||
|
||
Agent access: [companion](../agent-access-map/onboarding.md).
|
||
|
||
## 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](../../tests/runner-e2e/PRODUCT-JOURNEYS.md)
|
||
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](./README.md#before-driving-a-journey). Use a new isolated data directory and record deployment mode. A configured adapter may still need account authentication.
|
||
|
||
### `web-wizard`
|
||
|
||
Automated: [wizard tests](../../ui/src/components/OnboardingWizard.test.tsx) cover mocked wizard behavior; [onboarding browser suite](../../tests/e2e/onboarding.spec.ts) 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](../../.agents/skills/verify-paperclip/SKILL.md). 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](../../doc/onboarding-chat.md). 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](./runs-adapters.md#adapter-setup) and
|
||
[environment qualification](./execution-environments.md#environment-settings)
|
||
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](../../ui/src/components/OnboardingWizard.test.tsx) and
|
||
[runtime controls](../../packages/adapters/claude-local/src/server/sandbox-cli-version.test.ts)
|
||
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](../../ui/src/lib/qualify-claude-setup.test.ts)
|
||
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](../../cli/src/__tests__/onboard.test.ts) and [isolated test drive](../../cli/src/__tests__/test-drive.test.ts) 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](./access.md) for authenticated deployments and [agents](./agents.md) 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](../../ui/src/components/OnboardingWizard.tsx), [onboarding-state.ts](../../ui/src/lib/onboarding-state.ts). Tests: [OnboardingWizard.test.tsx](../../ui/src/components/OnboardingWizard.test.tsx), [onboarding-state.test.ts](../../ui/src/lib/onboarding-state.test.ts), [onboarding.spec.ts](../../tests/e2e/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](../../cli/src/commands/onboard.ts), [onboard-service.ts](../../cli/src/onboard-service.ts). Tests: [onboard.test.ts](../../cli/src/__tests__/onboard.test.ts), [onboard-service.test.ts](../../cli/src/__tests__/onboard-service.test.ts), [test-drive.test.ts](../../cli/src/__tests__/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.
|