## 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>
14 KiB
Private tasks and projects
Paperclip work is company-open by default. A task or project can instead be marked private when its title, discussion, documents, attachments, work products, or agent run traces should be limited to named participants.
Who can read private work
A private task is readable by its responsible user, creating user, current user or agent assignee, active task grantees, and members of its private project. Restrictions flow down through children and run-created handoffs. Sharing or assigning a task grants access to that task and its descendants; ancestors and siblings require a separate grant. An assignment grant stays active until it is explicitly revoked. Current assignment, ownership, private-project membership, and inherited access remain independent reasons for access. The sharing panel shows the source; revoking one grant does not remove other reasons. Making a parent private protects existing descendants in the same transaction. Moving a task under a private parent inherits privacy. A child cannot be made public while it inherits a private boundary; making a parent public leaves its existing private children private.
Private projects have a separate access-member list. A task-level grant can
expose one task without exposing its containing private project. Direct reads
by non-members return 404, and list, count, search, attention, status-card,
activity, run-history, and tree-control surfaces apply the same predicate.
Visible blocker and mention edges may show a locked identifier-only stub; they
never include the private task's title or content.
Audit logs remain company-wide because they are the sanctioned oversight path. They contain entity identifiers rather than private task content. Dashboard and sidebar aggregate counts also remain company-wide: they may include private work in totals, but do not expose titles, descriptions, or identifiers. The issue list/count APIs themselves are viewer-filtered.
Audited break-glass
Company owners and admins do not silently inherit private-task access. A normal
task detail request still returns 404. When an owner or admin has a legitimate
emergency need, they must deliberately request the task with
?breakGlass=true.
Every successful break-glass read writes both:
- an
issue.break_glass_readaudit row containing the actor, task id, and time; - a warning system notice on the private task so its owners can see that access occurred.
The flag does not change the canonical read predicate, create a grant, or make future reads implicit. Non-admin members and agents cannot use it.
Cloud customer-success inspection is a separate operator capability. When an
operator enables it, the dedicated Cloud-signed permit can read private task
content within its company scope. Ordinary users, agent API keys, and plugins
cannot use that permit. Cloud enforces the inspection grant, expiration,
revocation, replay protection, and audit trail; this path does not create a task
grant or a task break-glass notice. Operators who require task ACLs on every
content read must leave PAPERCLIP_CUSTOMER_SUCCESS_INSPECTION_ENABLED disabled.
See Cloud customer-success inspection support.
Agent runs and shared-agent residual risk
Issue-bound run detail, events, transcripts, logs, and workspace operations use the task ACL. Run authority is the intersection of the agent and the run's responsible user. Reusing an agent does not transfer a different user's private-task permission. Company run lists retain only timing/status/token/cost metadata for non-members so budget oversight continues without exposing task identity or run content.
Workspace operation records retain their original task and run sources even if those entities are deleted or the operation is relinked. Deletion preserves the audit record; unresolved sources make its details and log inaccessible. A company-scoped run does not override a private task linked to the operation.
Residual risk — trusted agents (
trust-agent). Paperclip enforces privacy on reads from the control plane, but an agent that legitimately processes a private task may write learned content into shared persistent memory, its home directory, an external tool, or a later public response. V1 deliberately trusts the agent not to exfiltrate that context. Use isolated execution workspaces and appropriately trusted agents for sensitive work; task ACLs are not a sandbox or data-loss-prevention system.
Plugins and notification/digest surfaces
Plugins (including any Slack notifier or digest plugin) are non-member
principals: they hold no company membership, task grant, or private-project
access. Rather than an allowlist of individually patched methods, the plugin
host centralizes the synthetic non-member check into shared helpers
(requirePluginReadableIssue, pluginReadableIssueIdsByIds,
pluginRedactRelationSummary) and routes every issue-derived read through
them. The complete inventory of issue-derived reads and their disposition:
- Direct issue content —
issues.list(SQL predicate),issues.get,issues.listComments,issues.listAttachments,issues.getAttachmentContent,issueDocuments.list,issueDocuments.get: a private task is filtered from list results, returnsnull/empty on soft reads, and reports "not found" (indistinguishable from missing) on document reads. - Subtree / orchestration —
issues.getSubtreeandissues.getOrchestrationSummary: a private root reports "not found"; an open root drops private descendants before any relation, document, run, or assignee is fetched, so no private row or its metadata enters the payload. - Relationship metadata —
issues.getRelations(and the summaries echoed byissues.setBlockedBy/addBlockers/removeBlockers, and the subtree relation maps): blocker/blocks edges pointing at a private task are dropped, recursing into nested terminal blockers, so its title, status, and assignee never surface even on a public task. - Interactions —
issues.listInteractions: a private task yields no interaction payloads.
A synthetic { type: "none" } actor resolves to the same public-only scope as
any other non-member. This is why a digest broadcast to a shared channel —
whose audience is non-members by definition — cannot carry private issue
content. Writes that operate on a task must also satisfy its read predicate; plugin
capabilities do not substitute for task access. Returned relationship summaries
remain redacted.
There is intentionally no plugin oversight exception: unlike the company-wide audit log, no plugin read path bypasses the predicate. A plugin that must surface private work would need an explicit, separately designed oversight capability; none exists today.
Residual metadata disclosure. A plugin still learns aggregate, content-free signals about private work that mirror the accepted dashboard/count disclosure:
issues.getOrchestrationSummaryreturns company-wideopenBudgetIncidents. Itscosts/token roll-up is limited to the readable subtree, and unreadable relationship edges are omitted entirely. No private title, body, comment, attachment, identifier, relationship target, or locked-edge signal is exposed.
Rollout modes
PAPERCLIP_ISSUE_PRIVACY_MODE=enforce is the default. shadow records
structured would-deny decisions without enforcing them and exists only for
rollout diagnosis. off disables the task predicate. Operators should not use
shadow or off when private-task confidentiality is required.
The production gate includes positive and negative checks: an authorized reader can read a shared child and its descendants, an unrelated reader cannot, and a warm HTTP or live subscription loses that grant after revocation. Privacy grants are read from the database without a cross-request positive cache.
Migration and current runtime integration
Migration 0313_private_task_access.sql adds the task/project ACL tables and
backfills privacy parent edges with indexed keyset batches. Run binding is derived
from native task identity, explicit issue identity, or legacy issueId/taskId context. Missing
source tasks remain issue-scoped tombstones. Context changes cannot turn those
runs into company-wide history. The migration is idempotent for preview installs;
existing explicit grants are preserved. Operators upgrading an unreleased preview
should inspect root grants created under its former whole-tree sharing semantics.
Migration 0314_private_task_draft_assets.sql accompanies enforcement and binds
historical inline images to their first owned task. Unbound drafts remain
uploader-only under the new asset-content guard.
Both privacy migrations use the Paperclip migration executor's explicit
nontransactional path. Indexes on existing tables build concurrently; invalid builds are repaired on
retry. DDL statements commit individually and each 1,000-row
keyset batch commits before advancing, releasing schema and row locks. The
migration journal is written only after all batches succeed; an interruption
leaves the migration pending and its idempotent statements can be replayed.
Bootstrap uses the same executor, and other migrations retain a transaction per
file. Apply these migrations with pnpm db:migrate, before enabling the new
server or private-task UI.
Private output uses the same predicate on native tool searches and task context, linked approvals, training exports, execution workspace APIs, stored run-response assets, and WebSocket delivery. Workspace access requires permission for every linked task. Chat publications recheck recipient identity and task access at the provider boundary: private output is withheld from shared channels and from DMs whose known recipients no longer qualify. This does not revoke Gmail or other connection credentials; connection permissions continue to apply independently.
CI leak-test inventory
The privacy regression gate is part of the normal server Vitest suite. Its surface coverage is intentionally distributed beside the routes and services it protects:
| Surface | Non-member regression coverage |
|---|---|
| Downward sharing, responsible-user intersection, mutation denial, provenance, live revocation | privacy-production-review.test.ts |
| Task detail, list, count, grants, documents, work products | issue-access-grants-routes.test.ts, company-search-service.test.ts |
| Search and machine extract | company-search-service.test.ts, company-search-extract-service.test.ts |
| Attention feed | attention-service.test.ts |
| Status-card hydrate and dry-run | status-cards.test.ts |
| Activity stream | activity-service.test.ts, activity-routes.test.ts |
| Run list, live run, detail, transcript, events, logs, operation history | heartbeat-run-privacy-routes.test.ts |
| Tree holds and tree control | issue-tree-control-routes.test.ts |
| Blocker and mention identifier-only stubs | issue-access-grants-routes.test.ts |
| Attachment content | issue-attachment-routes.test.ts |
| Private-project list and direct read | projects-list-archived-routes.test.ts |
| Plugin issue reads (list, get, comments, attachments, orchestration, subtree, relations, interactions, documents) | plugin-orchestration-apis.test.ts |
Adding a new task-derived read surface requires a non-member fixture in this gate before the surface can ship.
Project privacy management belongs to its recorded creator (the responsible user for agent-created projects), the personal-project owner, and administrators. Project read membership alone never allows publishing the project or changing its audience. Legacy projects recover ownership from their creation audit event; when that evidence is missing, an administrator manages their privacy.
Task privacy management hints
GET /api/issues/:id/privacy-constraints is available only to a principal who can read and manage that task. It returns the blocked scope kind and whether publishing leaves a personal project. It does not return protected parent or project names, identifiers, owners, or contents. This lets task owners manage their task without requiring access to its surrounding project. Visibility writes still enforce the canonical rules under the privacy-tree lock; these hints do not authorize a write.
Rollout switch and run-history reads
PAPERCLIP_ISSUE_PRIVACY_MODE controls the canonical opt-in issue/project privacy predicate:
enforce(default): return private issues only to implicit principals, issue grantees, or private-project access members; hide private projects from non-membersshadow: log structured would-deny decisions but preserve existing reads; use only for rollout diagnosisoff: skip the predicate and shadow logging
Grant checks read current database state; there is no positive privacy cache.
A run-history list is one read operation. It checks each distinct company, run scope, and task binding once, then applies that decision to the related rows in the same response. Every new list operation reads permissions again.
Sharing a task grants access to that task and its private descendants. Parents and siblings need separate grants. An agent's access is intersected with its run's responsible user's current access.
enforce is the production default. shadow and off disclose private data and
are only temporary diagnostic overrides. The old branch's historical sign-off
does not qualify the current runtime. See the sections above
for the model, validation coverage, break-glass behavior, and residual risks.
Issue-bound heartbeat runs inherit the same read predicate through the stored
heartbeat_runs.scope_kind = 'issue' and issue_id binding. Issue deletion
nulls the foreign key but preserves the explicit issue scope as a fail-closed
tombstone. Workspace-operation history is either deleted with its direct issue
or run binding, or remains bound to that fail-closed run tombstone, so it cannot
become company-level maintenance data through foreign-key nulling. In enforce mode, direct run detail, transcript,
event, log, and workspace-operation reads return 404 to non-members. Company
run-history and live-run lists retain a metadata-only row with timing, status,
token usage, and cost for budget oversight; issue identifiers, summaries, and
run content are omitted. Runs without an issue binding keep company-level
maintenance-run visibility.