Aron PrinsandClaude Opus 4.8
27d7a5ab4c
Syncs docs to parent release **v2026.831.1** (cumulative from
`v2026.824.1`, via merge-base `664052f`). Authored fresh against the
release tag; every claim verified at the tag.
## What changed
**New**
- **Kimi Code adapter** (`kimi_local`) — new reference page, wired into
the adapters overview, nav, and anchor-map source mapping.
**Reference**
- **Env vars** — `PAPERCLIP_WORKSPACE_REAPER_COOLDOWN_DAYS`, opt-in
`SENTRY_DSN`, and the operator controls `PAPERCLIP_HIDDEN_SETTINGS` /
`PAPERCLIP_SETTING_DEFAULTS`.
- **Instance Settings** — new "operator controls for hosted deployments"
section (hide surfaces / override defaults).
- **Node.js floor → 24.11.0** across installation, setup,
local-development, plugin dev, Modal, and the getting-started/terminal
guides.
- **Grok adapter** — `permissionMode` no longer defaults to `dontAsk`;
when unset no flag is passed, and `--always-approve` is the unattended
policy.
- **CLI `agent`** — Kimi skills install path (`~/.kimi-code/skills`) +
`KIMI_CODE_HOME`.
**Guides**
- **Onboarding** — rebuilt around a single-card wizard that opens on
creating your agent; the mission step is gone, the goal is set
afterward.
- **Settings unification** — Invites folded into a Members tab, one
shared settings nav, and the company brand color + per-company
attachment size limit removed (also reflected in the Companies and Cases
APIs).
- **Governance behavior** — silent-run detection and stranded-task
recovery no longer act on their own; agent thought text is excluded from
automatic comments; invalid agent credentials now return `401`.
**Changelog** — entry added for v2026.831.1.
## Gates
- `docs:build`, SEO metadata, crawlable-links, sitemap-lastmod
(194/194), lint-links, verify-nav — all pass.
- **Edit verification:** every new high-confidence claim verified at the
tag.
- **Tag-accuracy gate:** 31 files checked, **0 post-tag leaks**, 30
clean, 1 review (below).
## ⚠ Drift (Verify before acting — not auto-resolved)
Medium-confidence REST-route drift in `docs/reference/api/companies.md`
— the import-transfer routes may no longer exist at these paths (likely
a false negative from prefix/dynamic registration; confirm before
editing):
- `POST /api/companies/import/transfers`
- `PUT /api/companies/import/transfers/{transferId}/parts/{partIndex}`
- `GET /api/companies/import/transfers/{transferId}`
- `POST /api/companies/import/transfers/{transferId}/preview`
- `POST /api/companies/import/transfers/{transferId}/apply`
## ⚠ Review
- `docs/reference/adapters/kimi-local.md` — new page; the only flagged
claim is the `secret-id` JSON **example placeholder** (not a real
identifier). Authored directly from the adapter's config surface at the
tag.
## Screenshots (deferred)
288 of 342 registered screenshots are stale (org-wide rename +
settings/onboarding rewrites), tracked in `SCREENSHOTS_PENDING.md`.
Recapture is a follow-up pass — **the merged pages describe the new
onboarding/settings UI while screenshots still show the old flow until
then.**
---------
Co-authored-by: Claude Opus 4.8 <[email protected]>
3.9 KiB
seo_title, seo_description
| seo_title | seo_description |
|---|---|
| Local Development Setup | The fastest way to run Paperclip locally, using embedded PostgreSQL, local disk storage, and the local trusted deployment mode by default. |
Local Development
This is the fastest way to run Paperclip locally. The default path uses embedded PostgreSQL, local disk storage, and the local trusted deployment mode.
Use this page if you want to get the app running quickly, reset a local install, or start a private-network dev instance.
Prerequisites
- Node.js 24+ (24.11.0 or newer)
- pnpm 9+
Note: You do not need a separate PostgreSQL install for the normal local workflow.
Start The Server
pnpm install
pnpm dev
This starts:
- the API server at
http://localhost:3100 - the UI from the API server in dev middleware mode
The first start automatically uses embedded PostgreSQL if DATABASE_URL is unset. See Database for the storage modes behind that behavior.
One-Command Bootstrap
If you want setup and startup in one step, use:
pnpm paperclipai run
This is the best command for a first-time install because it:
- auto-onboards if no config exists
- runs
paperclipai doctorwith repair enabled - starts the server once checks pass
Use this when you want Paperclip to behave like an app, not a manually assembled stack.
Managed Dev Runner
The dev runner is 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.
Inspect or stop it with:
pnpm dev:list
pnpm dev:stop
Private Network Dev
If you want to access a local instance over Tailscale or another private network, run the authenticated private dev mode:
pnpm dev --tailscale-auth
Alias:
pnpm dev --authenticated-private
This configures the instance for authenticated private exposure and binds the server to 0.0.0.0.
If you need to allow additional private hostnames:
pnpm paperclipai allowed-hostname dotta-macbook-pro
See Tailscale Private Access for the full workflow.
Health Checks
After startup, verify the instance is alive:
curl http://localhost:3100/api/health
Expected response:
{"status":"ok"}
You can also confirm the API is serving company data:
curl http://localhost:3100/api/companies
Reset Local Data
To wipe the embedded database and start over:
rm -rf ~/.paperclip/instances/default/db
pnpm dev
This removes the local database only. It does not change your repo checkout or any other workspace data.
Worktrees And Isolated Instances
If you work from multiple git worktrees, do not point two Paperclip servers at the same embedded PostgreSQL data directory.
Create a repo-local isolated instance instead:
pnpm paperclipai worktree init
That command creates a repo-local .paperclip config and an isolated instance under ~/.paperclip-worktrees so the new worktree does not share the default embedded database.
Tip: This is the safest way to test docs or feature work in parallel across multiple branches.
Default Data Paths
| Data | Path |
|---|---|
| Config | ~/.paperclip/instances/default/config.json |
| Database | ~/.paperclip/instances/default/db |
| Storage | ~/.paperclip/instances/default/data/storage |
| Secrets key | ~/.paperclip/instances/default/secrets/master.key |
| Logs | ~/.paperclip/instances/default/logs |
These paths are under PAPERCLIP_HOME and PAPERCLIP_INSTANCE_ID. Override them when you want an isolated local instance:
PAPERCLIP_HOME=/custom/path PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run
Tip: If you are working in a second checkout or worktree, give it its own instance ID so you do not share the same embedded database by accident.