mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-06 10:48:12 +02:00
DottaandPaperclip
dda4dff645
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The onboarding command starts the local server and opens the first-run wizard. > - Interactive onboarding stopped opening the browser by default. > - Organization creation could also succeed in the API while the wizard stayed on the name step. > - The npm canary workflow did not prove that the published package could complete this path. > - This pull request repairs the startup and organization transitions and adds an exact-version canary smoke gate. > - The benefit is a quickstart that works for users and is tested after each canary publish. ## Linked Issues or Issue Description Related: #12557 covers a separate final-route onboarding handoff. **What happened?** Interactive `paperclipai onboard` runs did not open the onboarding page. The organization API request could succeed while a same-company context update caused the wizard to stay on the organization step. The canary release lane did not test the exact published npm package through this path. **Expected behavior** Interactive onboarding must open the browser once. A successful organization request must advance to the first-agent step when the surrounding context adopts the same organization. Each published canary must install in a clean environment and reach the model connection step. **Steps to reproduce** 1. Run `npx paperclipai@canary onboard --data-dir "$(mktemp -d /tmp/paperclip-canary.XXXXXX)"` in an interactive terminal. 2. Enter an organization name while the company context refreshes from the create response. 3. Observe that the browser does not open or that the wizard can remain on the organization step after the API creates it. 4. Inspect the canary release lane and observe that no post-publish onboarding test runs against the exact npm version. **Paperclip version or commit** The issue reproduced with `2026.901.0-canary.8` and the source state before this pull request. **Deployment mode** Local trusted quickstart with embedded PostgreSQL. The install source can be npm or a source checkout. ## What Changed - Open the browser once for interactive foreground onboarding. - Preserve explicit browser opt-outs and restore the prior environment value after startup. - Accept a same-company context update after organization creation and reject a different-company takeover with an explicit error. - Export the exact canary version from the publish job. - Install and test that exact npm version in a clean Playwright smoke job through the "Connect a model" step. - Upload server logs, traces, screenshots, and the Playwright report when the canary smoke fails. - Document the interactive default and headless opt-outs. ## Verification - `pnpm exec vitest run cli/src/__tests__/onboard.test.ts ui/src/components/OnboardingWizard.step.test.tsx --reporter=dot` passes with 37 tests. - `node --test scripts/__tests__/release-verify-workflow.test.mjs` passes with 9 tests. - `pnpm exec playwright test --config tests/e2e/playwright.config.ts tests/e2e/onboarding.spec.ts` passes with 2 tests. - `PAPERCLIPAI_VERSION=2026.901.0-canary.8 pnpm run test:canary-onboarding-smoke` passes against the published npm package. - `pnpm check:token-gates` passes. - `pnpm -r typecheck` passes. - `pnpm build` passes. - A fresh interactive source run opens the browser and reaches "Connect a model" after organization and agent naming. ## Risks - Low risk. Automatic browser opening only applies to interactive foreground onboarding. - `PAPERCLIP_NO_BROWSER=1` and `PAPERCLIP_OPEN_ON_LISTEN=false` keep headless runs silent. - A different organization context still blocks the pending create transition. - The canary package is immutable before the smoke runs. A smoke failure leaves the package published but makes the release workflow red. - This change does not modify REST APIs, database schemas, or shared data types. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex based on GPT-5. The runtime does not expose the exact deployment snapshot or context-window size. The model used reasoning, browser automation, repository tools, shell commands, code editing, and test execution. ## 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: Paperclip <noreply@paperclip.ing>
3.4 KiB
3.4 KiB
title, summary
| title | summary |
|---|---|
| Setup Commands | Onboard, run, doctor, and configure |
Instance setup and diagnostics commands.
paperclipai run
One-command bootstrap and start:
pnpm paperclipai run
Does:
- Auto-onboards if config is missing
- Runs
paperclipai doctorwith repair enabled - Starts the server when checks pass
Choose a specific instance:
npx paperclipai run --instance dev
paperclipai onboard
Interactive first-time setup:
pnpm paperclipai onboard
If Paperclip is already configured, rerunning onboard keeps the existing config in place. Use paperclipai configure to change settings on an existing install.
First prompt:
Quickstart(recommended): local defaults (embedded database, no LLM provider, local disk storage, default secrets)Advanced setup: full interactive configuration
Start immediately after onboarding:
pnpm paperclipai onboard --run
Quickstart defaults + immediate start:
pnpm paperclipai onboard --yes
When onboarding starts Paperclip from an interactive terminal, it opens the onboarding page in your browser once. Non-interactive terminals stay silent. Suppress browser opening explicitly for headless or automated runs with either environment variable:
PAPERCLIP_NO_BROWSER=1 pnpm paperclipai onboard --yes
PAPERCLIP_OPEN_ON_LISTEN=false pnpm paperclipai onboard --yes
On an existing install, --yes now preserves the current config and just starts Paperclip with that setup.
paperclipai doctor
Health checks with optional auto-repair:
pnpm paperclipai doctor
pnpm paperclipai doctor --repair
Validates:
- Server configuration
- Database connectivity
- Secrets adapter configuration, including AWS Secrets Manager non-secret env config when selected
- Storage configuration
- Missing key files
paperclipai configure
Update configuration sections:
pnpm paperclipai configure --section server
pnpm paperclipai configure --section secrets
pnpm paperclipai configure --section storage
--section secrets updates the deployment-level provider used as the fallback
for secrets that do not target a specific company vault. Per-company provider
vaults (named instances, default vault selection, multiple vaults per provider,
coming-soon GCP/Vault) live in the board UI under
Company Settings → Secrets → Provider vaults and the
/api/companies/{companyId}/secret-provider-configs API.
paperclipai env
Show resolved environment configuration:
pnpm paperclipai env
This now includes bind-oriented deployment settings such as PAPERCLIP_BIND and PAPERCLIP_BIND_HOST when configured.
paperclipai allowed-hostname
Allow a private hostname for authenticated/private mode:
npx paperclipai allowed-hostname my-tailscale-host
Local Storage Paths
| Data | Default Path |
|---|---|
| Config | ~/.paperclip/instances/default/config.json |
| Database | ~/.paperclip/instances/default/db |
| Logs | ~/.paperclip/instances/default/logs |
| Storage | ~/.paperclip/instances/default/data/storage |
| Secrets key | ~/.paperclip/instances/default/secrets/master.key |
Override with:
PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run
Or pass --data-dir directly on any command:
npx paperclipai run --data-dir ./tmp/paperclip-dev
npx paperclipai doctor --data-dir ./tmp/paperclip-dev