mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
## 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>
68 lines
2.7 KiB
Markdown
68 lines
2.7 KiB
Markdown
# Instance configuration switches
|
|
|
|
Environment switches and startup configuration that are not part of everyday local development.
|
|
|
|
## Internal Connection Token Brokers
|
|
|
|
Paperclip Cloud connector identities support `development`, `test`, `staging`,
|
|
and `production`. To enroll a self-hosted instance against the test broker, set
|
|
`PAPERCLIP_CLOUD_CONNECTOR_BASE_URL=https://test.paperclip.app`; its environment
|
|
is inferred as `test`. Managed instances also receive
|
|
`PAPERCLIP_CLOUD_CONNECTOR_ENVIRONMENT=test`. Standard Cloud broker hosts reject
|
|
identities for another environment, and enrollment keys remain local to the
|
|
selected broker.
|
|
|
|
Connection token exchanges carry a resolved parent credential, so their URLs
|
|
are public-only by default even in local/private deployments. To intentionally
|
|
use an internal broker, configure an exact hostname allowlist:
|
|
|
|
```sh
|
|
PAPERCLIP_TOKEN_BROKER_ALLOWED_HOSTS=broker.internal.example,10.0.0.42
|
|
```
|
|
|
|
Entries are comma- or whitespace-separated exact hostnames (no wildcards). The
|
|
host configured by `PAPERCLIP_PAGES_API_URL` is included automatically. Every
|
|
broker hostname is resolved once and the request is pinned to the approved
|
|
address; IPv4 and IPv6 link-local destinations remain denied even when their
|
|
host is allowlisted.
|
|
|
|
## HTTP Adapter Private Endpoints
|
|
|
|
HTTP adapters can call public HTTP(S) endpoints by default. Requests use the
|
|
same DNS-pinning guard as remote connections, do not follow redirects, and
|
|
reject loopback, RFC1918/private, and link-local or cloud-metadata destinations.
|
|
|
|
Server owners can opt a trusted private service in with a comma-separated list
|
|
of exact origins:
|
|
|
|
```sh
|
|
PAPERCLIP_HTTP_ADAPTER_PRIVATE_ENDPOINT_ALLOWLIST=http://hooks.internal.example:8080,https://10.0.0.42
|
|
```
|
|
|
|
Each entry must contain only a scheme, hostname, and optional port. Paths,
|
|
credentials, query strings, fragments, and wildcards are ignored. Matching is
|
|
by exact normalized origin, so allowing one port does not allow another.
|
|
Link-local destinations remain denied even when explicitly listed.
|
|
|
|
## Company Deletion Toggle
|
|
|
|
Company deletion is intended as a dev/debug capability and can be disabled at runtime:
|
|
|
|
```sh
|
|
PAPERCLIP_ENABLE_COMPANY_DELETION=false
|
|
```
|
|
|
|
Default behavior:
|
|
|
|
- `local_trusted`: enabled
|
|
- `authenticated`: disabled
|
|
|
|
## Cloud startup configuration
|
|
|
|
Cloud stores nonsecret startup choices in a private PostgreSQL singleton.
|
|
Bootstrap connection credentials stay in the supplied environment. A bounded
|
|
one-time config-file seed preserves existing choices, then later starts use the
|
|
database without loading home `.env` files or repairing worktree config. See
|
|
[Cloud runtime configuration](cloud-runtime-configuration.md) for field ownership,
|
|
secret handling, initialization order and migration interfaces.
|