Files
PaperClipAI/doc/DEVELOPING.md
T
DottaandClaude Fable 5.2 ac114d9479 refactor: cut DEVELOPING.md to a setup and workflow guide (#21670)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - `AGENTS.md` tells every contributor and agent to read
`doc/DEVELOPING.md` for setup, commands, testing, and worktrees
> - That file grew to 5,495 lines. Most of it was notes on how one
subsystem behaves, added one pull request at a time
> - Readers could not find the commands. Agents also read behavior notes
as rules
> - This pull request cuts `doc/DEVELOPING.md` to a 660-line setup and
workflow guide. It moves the subsystem notes to focused docs
> - The benefit is a guide that a person or an agent can read in full,
and a clear place for each kind of note

## Linked Issues or Issue Description

**Issue type**

Outdated or confusing documentation.

**Where is the issue?**

`doc/DEVELOPING.md`

**What's wrong?**

The file was 5,495 lines. It opened with 112 lines about case handoffs
before it reached Prerequisites. Unrelated sections sat below the
"OpenClaw Docker UI One-Command Script" heading. Statements about
current behavior read like policy.

**Suggested fix**

Keep setup, commands, and workflow in `doc/DEVELOPING.md`. Move each
subsystem note to a doc for that subsystem. Add an index.

## What Changed

- `doc/DEVELOPING.md` is now 660 lines: prerequisites, start dev, health
checks, local run, test drive, Docker, instance layout, database,
storage, secrets, worktrees, test commands, Storybook, CLI, and an index
of the other docs.
- 15 new docs hold the moved text without wording changes:
`ci-workflows`, `test-infrastructure`, `worktrees`,
`hot-restart-deploys`, `heartbeat-internals`, `runner-internals`,
`workspace-repositories`, `workspace-storage`,
`skills-and-teams-catalog`, `ui-internals`, `case-handoffs`,
`chat-connector-development`, `instance-configuration`,
`integration-api-notes`, `database-backups`.
- "Publish a branch Storybook" moved to `doc/STORYBOOK-DEPLOYMENT.md`.
The privacy rollout notes moved to `doc/ISSUE-PRIVACY.md`.
- Deleted about 280 lines: the story-by-story Storybook notes, "Agent
Artifact Uploads" (a copy of `doc/AGENT-ARTIFACTS.md`), two pointer-only
sections, "Workspace feature checks (2026-10-09)", and "Chat and task
navigation caching". The test-drive build-lock paragraph is now four
lines.
- Repointed every inbound link and every script or workflow comment that
named a moved section.
- `AGENTS.md` now says where a behavior note goes, so the guide does not
grow again.

## Verification

- A script split the file by line range. It asserts that each of the
5,495 source lines is kept, moved, or dropped exactly one time.
- A link check on every changed Markdown file found 0 missing files and
0 missing anchors.
- `node scripts/check-maps.mjs` passes.
- `node --test .github/scripts/tests/*.test.mjs`: 808 pass, 0 fail.
- `node --check` passes on the three scripts with changed comments.
- `pnpm verify` was not run. This worktree has no installed
dependencies, and the change has no runtime code.

## Risks

- Low risk. The change is documentation and comments only.
- A link to a moved section from outside this repository will land on
the top of `doc/DEVELOPING.md`.
- The new docs are not in the audited prose list in
`.github/scripts/ci-inputs.mjs`. An edit to one of them runs full CI. An
edit to `doc/DEVELOPING.md` does not. This PR does not change that list.

## Model Used

- Claude Fable 5.2 (`claude-fable-5-2`), Claude Code desktop, with tool
use.

## 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
- [ ] 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
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 18:02:27 -06:00

32 KiB

Developing

How to set up, run, and test Paperclip locally. The project runs fully in local dev without setting up PostgreSQL manually.

This file holds setup, commands, and everyday workflow only. Notes on how a subsystem behaves belong in that subsystem's doc; see More documentation.

Prerequisites

  • Node.js 24.11+
  • pnpm 9+

Start Dev

From repo root:

pnpm install
pnpm dev

This starts:

  • API server: http://localhost:3100
  • UI: served by the API server in dev middleware mode (same origin as API)

pnpm dev runs the server in watch mode and restarts on changes from workspace packages (including adapter packages). Use pnpm dev:once to run without file watching.

pnpm dev:once auto-applies pending local migrations by default before starting the dev server.

pnpm dev and pnpm dev:once are idempotent for the current repo and instance: if the matching Paperclip dev runner is already alive, Paperclip reports the existing process instead of starting a duplicate.

To run against a separate local state root, pass --data-dir. The dev runner translates it to an isolated PAPERCLIP_HOME before migration checks or server startup, so embedded PostgreSQL and other default instance state live under that directory:

pnpm dev --data-dir ./tmp/paperclip-dev

Pass the same option to the service-management commands so they use the isolated runtime-service registry:

pnpm dev:list --data-dir ./tmp/paperclip-dev
pnpm dev:stop --data-dir ./tmp/paperclip-dev

Issue execution may also use project execution workspace policies and workspace runtime services for per-project worktrees, preview servers, and managed dev commands. Configure those through the project workspace/runtime surfaces rather than starting long-running unmanaged processes when a task needs a reusable service.

Inspect or stop the current repo's managed dev runner:

pnpm dev:list
pnpm dev:stop

pnpm dev:once tracks backend-relevant file changes and pending migrations. When the current boot is stale, the board UI shows a Restart required banner. You can also enable guarded auto-restart in Instance Settings > Experimental, which waits for queued/running local agent runs to finish before restarting the dev server.

Mobile-friendly preview (pnpm dev:mobile)

The vite dev server serves an unbundled module graph. This is fast to reload on a local machine but too heavy for phones and tablets on slow links (airplane wifi, mobile data, distant tailnet peers). pnpm dev:mobile builds the UI once and serves the small production bundle on port 3101 via vite preview, proxying /api requests to the dev API on 3100.

  • pnpm dev:mobile — build the UI and start the preview server on :3101. Rebuild manually to pick up UI source changes.
  • pnpm dev:both — run pnpm dev and pnpm dev:mobile together with prefixed output and shared signal handling.

The preview server binds 0.0.0.0 and accepts any Host, so a tailnet or LAN address (e.g. http://<host>.ts.net:3101/) works out of the box. The /api proxy sets x-forwarded-host and x-forwarded-proto, which the server's board mutation guard uses to trust the browser's Origin — mutations from :3101 succeed against the API on :3100 without further configuration. An HTTPS tunnel in front of the preview server (ngrok, tailscale funnel) is also supported: the tunnel's x-forwarded-proto header is preserved when set.

Static UI mode compresses built JavaScript, CSS, and HTML with Brotli or gzip when the browser supports it. Hashed assets retain their immutable cache policy; byte-range responses retain their original representation. This reduces initial page downloads through bandwidth-limited HTTPS tunnels such as Tailscale Funnel. API responses and MCP transports keep their existing compression behavior.

Quick Health Checks

In another terminal:

curl http://localhost:3100/api/health
curl http://localhost:3100/api/companies

Expected:

  • /api/health returns {"status":"ok"}
  • /api/companies returns a JSON array

On *.staging.paperclip.app, the account menu shows the running server's short commit SHA below the user's email. Hover over it for the full SHA, or follow the link to inspect the commit on GitHub. Opening the menu refreshes /api/health so the label reflects recent deploys. The label is hidden on other hosts and when commit metadata is unavailable.

One-Command Local Run

For a first-time local install, you can bootstrap and run in one command:

pnpm paperclipai run

Note: private npm registry .npmrc + first-run onboarding

The first-run experience often starts with npx paperclipai onboard --yes (before you have a repo checkout). If your global ~/.npmrc sets registry to a private registry (for example GitHub Packages), npx may try to resolve paperclipai from that private registry and fail with E404.

Diagnostic:

npm config get registry

Workaround (cross-platform; force the public npm registry for this command):

npx --registry https://registry.npmjs.org paperclipai onboard --yes

paperclipai run does:

  1. auto-onboard if config is missing
  2. paperclipai doctor with repair enabled
  3. starts the server when checks pass

One-command isolated manual test drive

Use test-drive when you want to exercise the UI from a fresh checkout or SHA without completing onboarding by hand:

ANTHROPIC_API_KEY=... node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts test-drive
OPENAI_API_KEY=... node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts test-drive --harness codex --model gpt-5.4
OPENROUTER_API_KEY=... node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts test-drive \
  --harness opencode \
  --model openrouter/anthropic/claude-sonnet-4.5

The command creates a trusted-loopback instance in a unique OS temporary data directory, prints the absolute directory, runs onboarding and doctor non-interactively, creates Test Company with a CEO agent, then opens the browser. It runs in the foreground, does not install a background service, and does not create a goal, project, issue, task, or first heartbeat. Temporary directories are retained for inspection. Use --data-dir <path> to reuse one or --no-browser to suppress browser opening. Reused directories must use the embedded database: the command rejects database URL environment overrides and configs with database.mode: postgres, suppresses the invocation directory's .env when the server starts, and keeps the normal managed-service collision guard. The selected instance's own environment file still loads. The command selects the first available loopback port at or above 3100.

Source-checkout startup builds the shared and plugin SDK packages when needed and prints build progress. The command stays in the foreground after printing its ready URL; use Ctrl-C to stop it. An interrupted build is detected and rebuilt on the next start.

Claude uses ANTHROPIC_API_KEY; Codex uses OPENAI_API_KEY; OpenCode uses OPENROUTER_API_KEY and requires an openrouter/... model. --api-key-env can name a different source variable while the agent still receives the canonical variable. --api-key <value> is also supported and is mutually exclusive with --api-key-env; Paperclip redacts it from its own output, but also removes it from the JavaScript argument view before telemetry, diagnostics, or server startup. Wrappers, operating-system process listings, and shell history may still expose argument values. This is an explicit local test-drive tradeoff; use an environment-backed input when that exposure is not acceptable. In a linked Git worktree the command sets worktree runtime mode and safely arms Run tasks in this worktree for the current isolated instance. Primary checkouts and non-Git directories leave that experimental setting unchanged.

If the selected data directory already contains any company, test-drive preserves all companies, agents, and secrets and ignores the bootstrap flags. The worktree execution setting is the only value it may reconcile in that case.

Docker Quickstart (No local Node install)

Build and run Paperclip in Docker:

docker build -t paperclip-local .
docker run --name paperclip \
  -p 3100:3100 \
  -e HOST=0.0.0.0 \
  -e PAPERCLIP_HOME=/paperclip \
  -v "$(pwd)/data/docker-paperclip:/paperclip" \
  paperclip-local

Or use Compose:

docker compose -f docker/docker-compose.quickstart.yml up --build

See doc/DOCKER.md for API key wiring (OPENAI_API_KEY / ANTHROPIC_API_KEY) and persistence details.

Docker For Untrusted PR Review

For a separate review-oriented container that keeps codex/claude login state in Docker volumes and checks out PRs into an isolated scratch workspace, see doc/UNTRUSTED-PR-REVIEW.md.

Local Instance Layout

Every local install keeps runtime state directly under the selected instance root:

~/.paperclip/instances/default/                  # instance root
  config.json                                    # runtime config
  .env                                           # instance env file
  db/                                            # embedded PostgreSQL data
  data/
    storage/                                     # local_disk uploads
    backups/                                     # automatic DB backups
  logs/
  runtime-services/                             # managed local-service registry
  runtime-service-logs/                         # append-only managed-service stdout/stderr
  secrets/master.key                             # local_encrypted master key
  workspaces/<agent-id>/                         # default agent workspaces
  projects/                                      # project execution workspaces
  companies/<company-id>/agents/<agent-id>/codex-home/
                                                   # per-agent codex_local home

PAPERCLIP_HOME and PAPERCLIP_INSTANCE_ID override the home root and instance id respectively. paperclipai onboard echoes the resolved values in its banner (Local home: <home> | instance: <id> | config: <path>) so you can confirm where state will land before continuing.

Config updates preserve unrecognized top-level and nested keys so provider or plugin extensions survive configure and worktree port repair. Likely misspellings of known keys produce a warning but are not removed. If an existing config.json is malformed, onboard and configure first create a byte-for-byte sibling backup named config.json.invalid-1 (then -2, and so on). Repair from defaults requires an interactive confirmation; non-interactive runs stop without replacing the original.

Database in Dev (Auto-Handled)

For local development, leave DATABASE_URL unset. The server will automatically use embedded PostgreSQL and persist data at:

  • ~/.paperclip/instances/default/db

Override home or instance:

PAPERCLIP_HOME=/custom/path PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run

No Docker or external database is required for this mode.

Reset Local Dev Database

To wipe local dev data and start fresh:

rm -rf ~/.paperclip/instances/default/db
pnpm dev

Optional: Use External Postgres

If you set DATABASE_URL, the server will use that instead of embedded PostgreSQL.

Storage in Dev (Auto-Handled)

For local development, the default storage provider is local_disk, which persists uploaded images/attachments at:

  • ~/.paperclip/instances/default/data/storage

Configure storage provider/settings:

pnpm paperclipai configure --section storage

Secrets in Dev

Agent env vars support secret references. By default, secret values are stored with local encryption and only secret refs are persisted in agent config.

  • Default local key path: ~/.paperclip/instances/default/secrets/master.key
  • Override key material directly: PAPERCLIP_SECRETS_MASTER_KEY
  • Override key file path: PAPERCLIP_SECRETS_MASTER_KEY_FILE
  • Back up the key file and database together; either one alone is not enough to restore local encrypted secrets.

Strict mode (recommended outside local trusted machines):

PAPERCLIP_SECRETS_STRICT_MODE=true

When strict mode is enabled, sensitive env keys (for example *_API_KEY, *_TOKEN, *_SECRET) must use secret references instead of inline plain values. Authenticated deployments default strict mode on unless explicitly overridden.

CLI configuration support:

  • pnpm paperclipai onboard writes a default secrets config section (local_encrypted, strict mode off, key file path set) and creates a local key file when needed.
  • pnpm paperclipai configure --section secrets lets you update provider/strict mode/key path and creates the local key file when needed.
  • pnpm paperclipai doctor validates secrets adapter configuration, can create a missing local key file with --repair, and reports missing AWS Secrets Manager bootstrap env when that provider is selected.
  • Provider health is available at GET /api/companies/:companyId/secret-providers/health and reports local key permission warnings plus backup guidance.

Per-company provider vaults are configured in the board UI under Company Settings → Secrets → Vaults, backed by /api/companies/{companyId}/secret-provider-configs. The CLI does not own vault lifecycle today. See docs/deploy/secrets.md (Provider Vaults section) for the operator model.

Migration helper for existing inline env secrets:

pnpm secrets:migrate-inline-env         # dry run
pnpm secrets:migrate-inline-env --apply # apply migration

Deployment Modes

For mode definitions and intended CLI behavior, see doc/DEPLOYMENT-MODES.md.

For sandbox file synchronization, lock ownership, and the required upgrade procedure from directory locks, see Workspace restore locks.

Current implementation status:

  • canonical model: local_trusted and authenticated (with private/public exposure)

Worktree-local Instances

When developing from multiple git worktrees, do not point two Paperclip servers at the same embedded PostgreSQL data directory.

Instead, create a repo-local Paperclip config plus an isolated instance for the worktree:

paperclipai worktree init
# or create the git worktree and initialize it in one step:
npx paperclipai worktree:make paperclip-pr-432

This command:

  • writes repo-local files at .paperclip/config.json and .paperclip/.env
  • creates an isolated instance under ~/.paperclip-worktrees/instances/<worktree-id>/
  • when run inside a linked git worktree, mirrors the effective git hooks into that worktree's private git dir
  • picks a free app port and embedded PostgreSQL port
  • disables automatic database backups for the isolated instance
  • by default seeds the isolated DB in minimal mode from the current effective Paperclip instance/config (repo-local worktree config when present, otherwise the default instance) via a logical SQL snapshot

Seed modes:

  • minimal keeps core app state like companies, projects, issues, comments, approvals, and auth state, preserves schema for all tables, but omits row data from heavy operational history such as heartbeat runs, wake requests, activity logs, runtime services, and agent session state
  • full makes a full logical clone of the source instance
  • --no-seed defers database copying until the worktree is first used
  • --empty creates an empty isolated instance, with fresh signing secrets and no deferred copy; use this for synthetic test drives

--empty persists a .paperclip/seed-empty marker before writing the instance config. The CLI and managed runtime provisioner honor it even when a registered source instance is present. An explicit successful worktree reseed, or a replacement worktree init --force without --empty, clears the choice. While that marker exists, startup uses the instance's saved JWT and tool-action signing keys even if the shell inherited another instance's keys. Better Auth uses its saved key or the fresh instance JWT key. Missing saved keys stop startup.

Seeded worktree instances quarantine copied live execution by default for both minimal and full seeds. During restore, Paperclip disables copied agent timer heartbeats, resets copied running agents to idle, blocks and unassigns copied agent-owned in_progress issues, and unassigns copied agent-owned todo/in_review issues. This keeps a freshly booted worktree from starting agents for work already owned by the source instance. Pass --preserve-live-work only when you intentionally want the isolated worktree to resume copied assignments.

The same quarantine stops copied project/execution-workspace runtime desired states and clears copied runtime process claims. Without this reset, booting the cloned Paperclip database could restart a source workspace's dev service from the isolated instance, creating duplicate runners, port reassignment, and stale public URLs.

After worktree init, both the server and the CLI auto-load the repo-local .paperclip/.env when run inside that worktree, so normal commands like pnpm dev, paperclipai doctor, and paperclipai db:backup stay scoped to the worktree instance.

pnpm dev fails fast in a linked git worktree when .paperclip/.env is missing, instead of silently booting against the default instance/port. If that happens, run paperclipai worktree init in the worktree first.

See the worktree reference for deferred seeding, reseeding, repair, and every paperclipai worktree option.

Test Commands

The feature map is an optional reference for user entry points, targeted tests, manual verification recipes, and coverage gaps. Its generated page inventory lists current source references. The documented journeys have separate verification steps and do not run automatically from the map.

The sibling agent access map describes API and agent reachability for the same capabilities. The map contract defines synchronization, permissions and evidence. After map edits, run node scripts/check-maps.mjs for structural/reference checks; it does not start an instance or qualify access as an agent.

Agent worktree preflight

Prepare a new or updated agent worktree with one command:

node scripts/agent-preflight.mjs

It does what pnpm install --frozen-lockfile, the plugin SDK's ensure-build-deps, the Runner's ensure:eval-build-deps, build:rust, build and build:runner-binaries did, and skips work whose inputs are unchanged:

  • install is skipped when the lockfile, every package.json, patches/, Node and pnpm match this worktree's last install.
  • plugin SDK build runs scripts/ensure-plugin-build-deps.mjs, which builds @paperclipai/plugin-sdk and its @paperclipai/shared dependency and skips them when their content fingerprints match the last build. Like the Runner and the eval kernel, the SDK is imported through its built dist (plugin workers load it under plain Node), so the server and the restart-chaos harness cannot start without it. Both compile in about two seconds, so they do not use the shared cache.
  • Runner build is skipped when the Runner's build stamp is current. When another worktree built the same inputs (the build-input digest described under Reused Runner build in the server build, plus the compiler), the Runner and eval kernel dist are cloned from the shared cache. A restore skips the build's lint checks; CI runs them.
  • Runner debug binaries (runner/target/debug) are reused the same way, keyed by every file the Rust build reads.
  • A worktree without runner/target starts from a clone of a shared cargo seed that holds only third-party crates, so cargo compiles only the Runner crate.

The cache lives in ~/.cache/paperclip/agent-build (PAPERCLIP_AGENT_CACHE_DIR moves it, PAPERCLIP_AGENT_CACHE=0 or --no-cache turns it off). Entries are keyed by content and toolchain, never by path or mtime, are written once with an atomic rename, and are restored as APFS clones, so concurrent worktrees can share them. The seed never holds the Runner crate: cargo records its out-of-package includes by absolute path, so units from another checkout cannot be trusted. Keep the cache on the worktrees' volume so clones stay cheap. --explain prints each step's decision; --skip-rust-debug skips the debug binaries.

Do not share CARGO_TARGET_DIR between worktrees: cargo serializes builds on its lock, and the Runner crate's absolute-path dependency records would make one worktree's freshness check read another's files. The preflight disables the cache when CARGO_TARGET_DIR is set.

Incremental local verification

Use the local verification entry point for ordinary issue work:

pnpm verify
pnpm verify --explain
pnpm verify --base origin/master

The command compares the actual working tree with the merge base of the supplied local ref, including committed, staged, unstaged, deleted, renamed, and untracked paths. The default ref is local origin/master, falling back to master; it does not fetch. Tests read the current working-tree bytes. CI must still verify the final committed revision. The task/input policy, conservative import and file-read graph, exact Vitest specifications, and stable test runner are shared with CI. Serialized server tests retain their owner. Native server tests remain in local coverage. Selected chat tests retain six sequential isolated line shards.

When the change touches packages/shared/src, packages/plugins/sdk/src, or an SDK build input such as pnpm-lock.yaml, the command first checks the committed SDK public input pins (tests/runner-e2e/source-sdk-public-inputs.json) against the working tree. If they are stale it exits 1 and prints the refresh command: commit the change, run node tests/runner-e2e/source-sdk-public-inputs.mjs $(git rev-parse HEAD) --write, and commit the updated registry. Otherwise the Runner support suite fails in CI.

Successful selected checks with complete input graphs are reusable in this worktree. Opaque filesystem, subprocess, network, generated/untracked-module, and unreviewed dependency consumers continue to run fresh. A selected pass never satisfies a full run. Non-isolated projects and uncertain selection require broader verification. The command prints the local test scope and remaining CI lanes.

An unchanged repeat can reuse both graph discovery and passing checks. Keys include actual tracked and non-ignored file contents (including dirty and untracked files), the shared audited-prose exclusions, dotenv files, lockfile, installation metadata, dependency bindings and installed package contents, the complete effective child environment, Node/pnpm/Rust toolchains, platform, checkout path, comparison, and selection. Values from the environment are hashed, not written to results. External database/live-test settings and out-of-checkout source symlinks disable reuse. Cache state lives under the ignored .turbo/local-verify/ directory and is not shared across worktrees or machines. Installed package content digests are memoized against file identity, size, mode, and nanosecond modification/change times; every check rescans the installation. Generated Vite/cache directories are excluded. The first run after installation reads package contents; unchanged repeats avoid reading those bytes again. last-run.json retains the latest completed execution's status and scope. Failed/interrupted attempts do not publish passes. Inputs changed during a run invalidate its result.

Exit 2 reports a broad input, incomplete graph, or unsupported selection. It does not silently launch the full suite or claim affected coverage passed. Use focused checks and required CI to close that gap, or explicitly request a broad local run:

pnpm verify --full
pnpm verify --no-cache

--full executes the complete existing Vitest path with fresh integration coverage. --no-cache bypasses pass/plan reuse and does not save passes. A fresh failed or interrupted attempt removes its old reusable pass. Required CI on the final tested revision may supply broad typecheck/build/test coverage for a PR handoff; do not repeat a full local suite solely because a chat resumed or a PR is ready. Keep release checks and any real browser, provider, local-platform or acceptance proof.

The full local Vitest commands remain available:

pnpm test

pnpm test runs the Vitest suite only. Its default chat integration coverage runs first in six sequential, exact-cover child processes, each with its own home, config and embedded PostgreSQL. The remaining server invocation excludes that chat file once and retains the native Runner suites. This bounds shared fixture and process lifetime without increasing concurrency or changing case assertions or timeouts. An explicit PAPERCLIP_TEST_DATABASE_URL retains the original single, serial database path. Explicit --group invocations and CI shard routing are unchanged.

For interactive Vitest watch mode use:

pnpm test:watch

Browser suites stay separate:

pnpm test:e2e
pnpm test:release-smoke

These browser suites are intended for targeted local verification and CI, not the default agent/human test command.

The default E2E configuration builds the UI into server/ui-dist before starting its throwaway instance and serves that build with PAPERCLIP_UI_DEV_MIDDLEWARE=false. This exercises the shipped assets, including service-worker takeover and reload, without traversing the development server's unbundled module graph on each navigation. Browser assertion deadlines and retries remain unchanged. Use pnpm dev separately when verifying Vite/HMR behavior.

For normal issue work, start with the smallest targeted check that proves the change. Use the incremental command above and required final-revision CI for PR handoff. Run broad local checks when an unresolved risk or explicit qualification needs them.

Storybook

The board UI Storybook keeps stories and Storybook config under ui/storybook/ so component review files stay out of the app source routes.

Stories are grouped in ui/storybook/stories/<feature-area>/. Feature recipe navigation controls the sidebar. Shared fixtures live in ui/storybook/support/. Keep each suite's explicit meta id when changing titles or locations so existing review links remain valid. Author capability associations, implementation/data classification and durable limitations in the story's parameters.paperclip.

Storybook start/build generates the catalog, feature Overview pages, and literal sidebar order from the checked-out sources. ui/storybook/generated/ and ui/storybook/.storybook/preview.tsx are ignored build outputs. Shared preview fixtures and decorators live in preview-base.tsx; generation never edits it. UI typechecking also generates the inputs on a fresh checkout.

Run node scripts/storybook-catalog.mjs to assemble the local Markdown indexes, verification routes and page inventory under maps/generated/. Use --check for validation without writes. These outputs are not committed. Use Git diffs to select affected sources for review; do not maintain review fingerprints or append a shared review journal. Record executed evidence in the PR, issue, or CI result.

The Storybook map contract describes annotations and the published guide. Use maintain-storybook for source alignment and review-storybook for rendering and interactions. Generated guides, example counts and structural checks do not establish production behavior. Feature recipes retain optional verification scope guidance; the feature/access structural check needs no Storybook runtime.

pnpm storybook
pnpm build-storybook

These run the @paperclipai/ui Storybook on port 6006 and build the static output to ui/storybook-static/.

Run one story suite's browser checks against a running Storybook with:

STORYBOOK_TEST_BASE_URL=http://localhost:6006 pnpm exec playwright test <name>.spec.ts --config=tests/storybook-visual/playwright.config.ts --project=stories

To publish a branch's Storybook, see Publish a branch Storybook.

The Storybook visual regression suite uses external PNG baselines instead of committed screenshots:

pnpm test:storybook-visual
pnpm test:storybook-visual:update

pnpm test:storybook-visual downloads and verifies the baseline archive from tests/storybook-visual/baseline-manifest.json before running Playwright. Accepted visual changes should update the manifest metadata and publish a new immutable archive with pnpm storybook-visual:baseline pack and pnpm storybook-visual:baseline upload; do not commit generated PNG snapshots.

Known limitation: Storybook visual baselines are Linux/Ubuntu-only. The manifest pins the capture environment to ubuntu-24.04 and the Playwright suite uses pixel-exact comparison, so local runs on macOS, Windows, or other non-matching platforms can report false-positive diffs from font rasterization and subpixel rendering. Use the Storybook Visual GitHub Actions workflow on ubuntu-latest as the source of truth, or run locally in a matching Linux environment before accepting or updating baselines.

PR visual checks are opt-in while the suite stabilizes. Add the storybook-visual label to a PR, or run the Storybook Visual GitHub Actions workflow manually, to produce downloadable Playwright report/test-result artifacts. Normal PR visual runs use read-only repository permissions and do not upload or mutate baseline objects.

CLI Client Operations

Paperclip CLI includes client-side control-plane commands in addition to setup commands.

Quick examples:

npx paperclipai issue list --company-id <company-id>
npx paperclipai issue create --company-id <company-id> --title "Investigate checkout conflict"
npx paperclipai issue update <issue-id> --status in_progress --comment "Started triage"

Set defaults once with context profiles:

npx paperclipai context set --api-base http://localhost:3100 --company-id <company-id>

Then run commands without repeating flags:

pnpm paperclipai issue list
pnpm paperclipai dashboard get

See full command reference in doc/CLI.md.

More documentation

Background on how each area works. These can be out of date; the code and its tests are the source of truth.

Area Doc
Schema, migrations, DB clients DATABASE.md, database-backups.md
CI routing, trusted PR workflow, lockfiles, typecheck lane ci-workflows.md
Test tooling internals, typecheck memory, benchmarks, smoke tests test-infrastructure.md
Worktree commands and seeding worktrees.md
Restarts and deploys hot-restart-deploys.md
Heartbeat service and background workers heartbeat-internals.md
Paperclip Runner RUNNER-INTEGRATION-PLAYBOOK.md, runner-internals.md
Workspace directories, repositories, caches workspace-repositories.md
Managed-cloud and remote workspace storage workspace-storage.md
Skills and teams catalogs skills-and-teams-catalog.md
Board UI internals, saved read cache ui-internals.md
Storybook publishing STORYBOOK-DEPLOYMENT.md
Cases experiment case-handoffs.md
Slack chat in local dev, connector diagnostics chat-connector-development.md
Environment switches and Cloud startup configuration instance-configuration.md
Small integration API contracts integration-api-notes.md
Private tasks and projects ISSUE-PRIVACY.md
Agent deliverables AGENT-ARTIFACTS.md