PaperClipAI/maps/feature-map/onboarding.md

Onboarding and first work

An operator can start an instance, create a company, configure its first agent, and reach a real first task. Instance setup and company onboarding are separate steps.

Implementation: web wizard, CLI setup.

Agent access: companion.

Sub-features

• instance: choose local instance configuration and start the server.
• company: create a company with its identity and initial agent.
• adapter: choose an available harness, model, account, and execution environment.
• first-task: leave setup with a task whose execution or missing prerequisite is visible.
• resume: return to an incomplete wizard without losing saved state.

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.

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 created first task, verify the selected agent and company, and inspect its output or explicit authentication gate. Reload both company and task.

For Codex or Claude, choose the harness and leave runner selection automatic to prove the first-agent default. On a qualified target it saves Paperclip Runner; Advanced also permits Legacy. 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. Use runner validation and environment qualification for the prerequisites; a successful login alone is insufficient.

For a new Claude agent on an explicit immutable sandbox image, 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. Named snapshots and mutable image tags do not gain qualification through this flow. Helper controls and mounted wizard/new-agent tests use mocks; live managed acceptance remains a separate gate.

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.

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.