## 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>
7.0 KiB
Project source repositories
The Create project dialog accepts a name and optional GitHub repository selections.
It uses the same RepositoryEditor as project Configuration. Description remains
editable in Configuration. Status, goal links, and target dates remain supported by
the API but are omitted from creation; Status and Goals are omitted from Configuration.
Old Overview URLs and saved Overview preferences redirect to Configuration.
API and persistence
GET /api/companies/:companyId/project-repositoriesreturnsrepositories,connectionCount, andfailedConnectionCount. Repository IDs are GitHub's stable numeric IDs represented as strings. Results are deduplicated across accessible grants and sorted by full name. Connection labels are display provenance only.POST /api/companies/:companyId/projectsaccepts optionalrepositoryIds. The server resolves new selections through the caller's authorized GitHub grants before creating the project and all repository workspaces in a transaction. The existingworkspaceinput remains supported; it cannot be combined withrepositoryIds.PUT /api/projects/:id/repositoriesaccepts the selectedrepositoryIdsarray. Accessible retained IDs refresh their canonical name and URL after renames or transfers; unavailable retained IDs keep their saved metadata. Replacement is transactional. Existing selections may be retained or removed even if their GitHub connection becomes unavailable. New identities require current access. Legacy URL workspaces are preserved, and matching legacy URLs are adopted without creating a duplicate workspace. Local/remote workspace locations survive detaching their repository.
No schema migration is required. Selected repositories are normal project workspaces
with metadata.githubRepositoryId. Existing manual repoUrl workspaces remain
editable through Configuration and the workspace API. One workspace remains primary.
Tasks materialize the other distinct repositories as editable checkouts inside their
workspace, including when no local folders are configured. Local execution and sandbox
staging use the same layout; sandbox restore preserves each repository's Git history.
See Project Repository Checkouts for paths,
ignore rules, and reuse behavior. Responsible-user credential rules still apply.
A repository selection never delegates credentials.
Fresh tasks using the default repository workspace can clone the same authorized
remote into a company- and task-scoped source directory when an existing project
checkout contains another task's restricted workspace. The clone uses the run's
Git connection and keeps separate Git metadata. Source access checks still apply
before the task workspace is published. Low-trust review runs cannot use this
persistent clone fallback. This fallback does not copy unpublished
local changes or replace reused workspaces, explicit workspace selections, pinned
branches, or repositories that only exist on the local filesystem.
Configured branch templates must derive the branch from the task identifier, ID,
title, or slug. Literal or task-independent templates retain the source denial,
so a fresh clone cannot replace a selected local branch with a new empty branch.
New implicit Git workspace defaults record their project-source provenance.
An untyped checkout binding from an older task is ambiguous and keeps the denial,
including explicit checkout IDs and inherited parent sources. Admission rechecks
the current binding rather than inferring a default from the selected checkout ID.
When the denial is retained, the run stops before the agent starts with a
configuration_incomplete failure (reason workspace_source_restricted). The task
is blocked with a notice that tells the owner to push unpublished work and select a
new workspace, or to grant access to the restricted task, then retry. Paperclip
does not report this owner action to Sentry as an unexpected run failure.
This applies to both isolated-source checks and repository admission for a shared
project workspace. Neither path replaces the existing workspace or retries the
same access denial automatically.
Startup validation of these recorded defaults keeps the task's effective workspace
strategy. It does not substitute the agent's shared strategy or grant project writes.
Workspace close and reopen use the recorded isolated source. Both operations
verify its company, task, repository URL, and separate Git storage before use.
Discovery and setup
The server checks company membership, grant ownership/status, and organization-grant
audiences before loading provider metadata. Connection managers receive no bypass to
another person's personal repositories. Managed GitHub grants refresh installation
access; PAT connections use paginated /user/repos. Provider failures are reported
without exposing provider error bodies or credential material. Successful connections
remain selectable when another connection fails.
Task repository preparation distinguishes a temporary provider refusal from a completed catalog that denies access. Before provider dispatch, known HTTP availability failures and exhausted quotas use the existing bounded infrastructure retry and provider deadline. Each successor discovers repositories again under the same responsible user's current grants. Empty successful catalogs, revoked grants, and permission denials remain terminal. A partial catalog can authorize a requested repository only when that repository is present.
ConnectionSetupFlow owns provider setup in both Apps and project dialogs. Task
intents retain their existing callback protocol. Standalone dialogs verify the saved
connection through the API after the sign-in popup returns to the instance. Project
name and repository drafts stay mounted across setup and cancellation.
UI review and verification
Proposals/Project repos contains the reviewed states, including loading, failure,
empty search, disconnected GitHub, multiple repos, legacy URLs, forty selections,
mobile, and short viewports. The configuration story composes the production page
properties through an explicit repositories slot. Story setup and saves use fixtures.
- Shared visual control:
ui/src/components/RepositoryEditor.tsx. - Data and error handling:
ProjectRepositoryInput.tsx. - Configuration persistence and legacy editing:
ProjectRepositories.tsxandLegacyProjectRepository.tsx. - Production dialog:
NewProjectDialog.tsx. - Server tests:
project-repositories.test.tsandproject-repositories-persistence.test.ts. - Browser acceptance:
tests/e2e/project-repositories.spec.ts.
The browser suite uses a real temporary server and database. It verifies creation, forty persisted repos, mobile scrolling, removal/save/reload, legacy URL editing, and rejection without a partial project. Provider discovery is simulated in the picker rejection test. GitHub network and popup behavior use deterministic fixtures in integration/component tests; the suite does not authorize a real GitHub account.