Work products and conversations
Paperclip keeps the work record close to the issue that gives it meaning. Documents, files, agent outputs, chat turns, review notes, and links to outside systems remain connected to the task and can be found again through company search. This page complements Organization work management, Projects, goals, and teams, and Chat integrations.
Collaboration record
The collaboration record is the set of durable work products and discussion points that explain how an issue moves from request to result. It brings together human and agent activity without treating every record as the same kind of object.
| Record | Main purpose | Main context |
|---|---|---|
| Artifact | Make produced output easy to browse and revisit | Company and issue |
| Document | Hold structured, editable work such as a plan | Issue, routine, or case |
| Comment or chat turn | Record a request, answer, decision, or progress note | Issue timeline |
| Annotation | Tie a review thread to selected document text | Document revision |
| External object | Show a useful view of a linked object in another system | Issue text and related work |
| File resource | Safely preview or download a file in a linked workspace | Issue and workspace |
| Search result | Find records across these surfaces | Company |
Work products
Work products are the visible outputs of work. The company-level artifact view gathers agent-produced documents, direct attachments, and artifact work products into one browseable record while keeping each item linked to its source issue.
Artifacts
An artifact is a produced item that a person may need to inspect, share, or download after an issue run. It may be a document, image, video, text item, or other file, and its card gives a preview when the content supports one. The artifact view can show a flat list or group items by task or parent task so a large set of outputs stays tied to the work that produced it.
Artifacts do not replace the issue timeline. They provide a focused way to find outputs, while each artifact still points back to the issue and may show its project and producing agent.
References: server/…/company-artifacts.ts• L318-473 server/…/company-artifacts.ts• L475-721 ui/…/Artifacts.tsx• L32-45 ui/…/ArtifactCard.tsx• L151-239
Documents
A document is a named body of work attached to a parent record. The current body is paired with a revision history, so people and agents can update or restore work while retaining the sequence of changes. A document can also be locked when its content must not be changed in place. A later write can either fail or create a new document with an available key when the caller chooses that strategy.
Issue documents commonly hold plans and other structured work. The same document model also supports routine and case records, which lets review and discussion use the same kind of durable work surface outside an issue. Updates require the current revision as a base, and a restore creates a new latest revision rather than erasing the history.
Document writes also distinguish protected work from ordinary edits. A locked document rejects normal updates, while a caller that chooses the create-new strategy receives a new document with an available key and a link back to the locked source. This keeps the protected record unchanged while allowing new work to continue beside it.
References: server/…/documents.ts• L45-112 server/…/documents.ts• L114-198 server/…/documents.ts• L200-516 server/…/documents.ts• L583-814
Conversations
Conversations capture the human and agent exchange around a work item. The issue timeline can combine comments with system events, linked runs, queued messages, and live output, so a reader can follow both what people said and what the system did.
Issue comments and chat
An issue comment is a durable message with an author, time, and optional run or system context. The issue chat surface presents comments with markdown, mentions, attachments, feedback, run transcripts, tool activity, and system notices when those records exist. A queued message remains visible until its target run handles it or a person interrupts it.
Comments update the issue's recent activity and support direct links to a comment. Human, agent, and system authors remain distinct because the distinction explains who made a request, who produced an answer, and which state change came from Paperclip itself.
References: server/…/issues.ts• L8616-8679 server/…/issues.ts• L8791-8907 ui/…/IssueChatThread.tsx• L434-577 ui/…/CommentThread.tsx• L885-1087
Board chat
Board chat is a company-level conversation for operating the organization rather than discussing only one issue. It uses a standing “Board Operations” issue as its durable conversation and decision log, which means the history survives page reloads and remains part of the normal issue record.
The board assistant can stream a reply while it works, then saves the final reply as a comment. External chat connectors extend this record to provider conversations. A connector maps inbound provider events to Paperclip conversations and maps selected issue comments or board messages back to the provider. The connector activity view records inbound deliveries, outbound publications, and provider actions. It keeps failed deliveries replayable only when they are bound to an issue and blocks replay while an outbound result is unknown, so an operator can resolve uncertainty before sending work again.
References: server/…/board-chat.ts• L20-35 server/…/board-chat.ts• L97-121 server/…/board-chat.ts• L148-205 server/…/board-chat.ts• L353-380 server/…/chat-channels.ts• L358-465 server/…/chat-channels.ts• L28479-29112 server/…/chat-channels.ts• L28750-28825
Document review
Document review adds discussion to a work product without changing the document body. Review threads preserve the selected text and let a reader discuss, resolve, or reopen a point beside the document.
Annotations
An annotation is a review thread anchored to selected document text. A new thread must match the current revision, and its first comment starts the discussion. When the document changes, open threads try to follow the text. A thread can become stale or orphaned when the old location is uncertain or gone.
Annotations support issue, routine, and case documents. The panel keeps the thread list aligned with document order and shows the revision used by the review, which helps a reader judge whether a comment still applies.
References: server/…/document-annotations.ts• L127-193 server/…/document-annotations.ts• L284-315 server/…/document-annotations.ts• L411-496 server/…/document-annotations.ts• L957-1030 ui/…/DocumentAnnotationPanel.tsx• L127-171 ui/…/CommentThread.tsx• L317-499
External objects
An external object is a recognized object behind a link to another system, such as a pull request, issue, lead, or deployment. Paperclip detects supported links in issue text, comments, and documents, then keeps a shared object identity for every mention so one remote object can appear in several parts of the work record.
The displayed status is useful but not a claim that the remote system is always reachable. Each object also has a liveness state such as fresh, stale, authentication required, or unreachable. Paperclip refreshes non-terminal objects when needed and exposes the result inline, in related work, and in project summaries.
References: server/…/external-objects.ts• L24-88 server/…/external-objects.ts• L168-207 server/…/external-objects.ts• L446-584 server/…/external-objects.ts• L615-773 ui/…/ExternalObjectPill.tsx• L100-199
File resources
File resources give a work conversation a safe view of files that live in a project or execution workspace. They are different from uploaded issue attachments: an attachment is a stored output linked to an issue, while a file resource refers to a path in a workspace and is read only when a person or agent requests it.
Workspace files
Workspace file access can list files, resolve a referenced path, preview supported content, or prepare a download. The system can use an execution workspace, a project workspace, or an explicitly selected project/workspace pair. It can list all files, recent files, or changed files, and it can search by relative path.
The file view is bounded by the workspace root and hides paths that may contain source-control data, build output, or secrets. Remote or unavailable workspaces return an explicit unavailable result rather than pretending that a file can be opened.
When markdown contains an eligible workspace file reference, the reader can open it in the file viewer after availability is checked. This lets comments and chat point to live work files without copying their contents into the collaboration record.
References: server/…/workspace-file-resources.ts• L287-349 server/…/workspace-file-resources.ts• L534-655 server/…/workspace-file-resources.ts• L867-958 server/…/file-resources.ts• L351-361 server/…/file-resources.ts• L529-659 ui/…/file-resources.ts• L46-97 ui/…/WorkspaceFileMarkdownBody.tsx• L24-59
Record relationships
The issue is the main meeting point for work products and conversations. External chat adds another path to the same issue record: a provider message is accepted as an inbound delivery, linked to a Paperclip conversation and issue, and may later produce a publication back to the provider.
The following flow shows how a task can accumulate durable output, review context, outside references, workspace links, and provider conversation state while company search provides a second way to reach the same record.
flowchart TD
Provider[External chat provider] -->|verified webhook| Delivery[Inbound delivery]
Delivery --> Conversation[Paperclip conversation]
Conversation --> Issue[Issue]
Issue --> Comments[Comments and chat]
Issue --> Documents[Documents]
Documents --> Annotations[Annotation threads]
Issue --> Artifacts[Artifacts and attachments]
Issue --> Workspace[Workspace file resources]
Comments --> External[External objects]
Documents --> External
Issue --> External
Comments -->|selected comment| Publication[Provider publication]
Issue -->|board message| Publication
Publication --> Provider
Delivery --> Activity[Connector activity]
Publication --> Activity
Issue --> Search[Company search]
Documents --> Search
Comments --> Search
Artifacts --> Search
The links are deliberate. A document review can lead to a comment, a comment can mention an outside object, an issue can point to a live workspace file, and a selected comment can be sent to a linked provider conversation. The connector keeps uncertain sends visible so an operator can resolve them before replaying work that might already have reached the provider.
Search
Company search is the cross-record entry point for finding work. It searches issue identity and text, comments, documents, artifacts, agents, and projects, then returns ranked results with snippets and links to the most useful matching context.
Search scopes
Search can cover all supported record types or focus on issues, comments, documents, artifacts, agents, or projects. Issue filters narrow results by status, priority, assignee, project, label, and update time. Results include counts and filter counts so a person can understand the size of the matching set before changing scope.
Search also supports phrase and token matching with limited typo tolerance for issue text. A result may point directly to a matching comment or document section, while an artifact result keeps its source and media kind so the reader can choose the right view.
References: server/…/company-search.ts• L416-451 server/…/company-search.ts• L454-488 server/…/company-search.ts• L557-583 server/…/company-search.ts• L990-1071 server/…/company-search.ts• L1204-1337 server/…/issues.ts• L5851-5925 ui/…/search.ts• L4-44
Provider search
Provider search adds a user-authorized view of Slack content when the company has an active Slack connection. It is separate from the company search index: a linked Paperclip user connects the matching Slack identity through OAuth, and the resulting grant is limited to search scopes and read-only use. Native Slack search is not assumed to be available through the bot connection.
The search connection is tied to the Paperclip user, Slack user, workspace, and current app configuration. A user can view its state, connect or disconnect it, and authorized agents can use Slack search tools only during a task run that still has an assigned and authorized Slack resource. This keeps provider search tied to the person and work context that granted it.
References: server/…/slack-tools.ts• L18-32 server/…/slack-tools.ts• L88-165 server/…/slack-search-oauth.ts• L28-55 server/…/slack-search-oauth.ts• L82-119 server/…/slack-search-oauth.ts• L159-241 server/…/slack-search-oauth.ts• L489-699 server/…/connector-runtime.ts• L55-145 server/…/chat-channels.ts• L38267-38367
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the artifact source and media-kind contract aligned between the company artifact service, shared search results, and the artifact cards. A mismatch can make an output searchable but not previewable.
- Preserve issue context when adding a new work-product source. Artifact links, grouping, project filters, and search counts all depend on the source resolving to an issue.
- Keep document revision writes, locked-document redirects, and annotation remapping aligned. A document change that skips the annotation path can leave open review threads on an old revision, while a redirect that does not expose its new key can detach later work from the intended document.
- Keep the locked-document strategy visible to callers. A normal write must remain a conflict, while a create-new write must return the replacement key and preserve the link to the protected document.
- Keep comment author fields and board-concierge handling aligned. Changing the sentinel or author rules can turn a saved board reply into a user turn in the next assistant prompt.
- Keep external-object mention detection aligned with every editable source. Updating issue text, comments, or document bodies without refreshing mentions makes the related-work and status views stale.
- Keep workspace path policy shared by list, resolve, preview, and download. A weaker rule in one route can expose a file that another route correctly denies.
- Keep chat connector bindings aligned across webhook admission, conversation linkage, publication targets, and issue bindings. A provider event that loses its issue context can create an external message that cannot be reviewed or safely replayed.
- Keep connector activity states and replay rules aligned. A delivery or publication marked as uncertain must require an operator decision before a retry that could duplicate provider output.
- Keep external provider access checks on both read and mutation paths. Listing a conversation or activity record must not grant the connection-management or publication authority needed to change it.
- Keep Slack search grants tied to the linked Paperclip user, Slack identity, workspace, and app revision. A refreshed or reused grant must not become a general provider token or survive a changed connection binding.
- Keep agent Slack tool calls tied to the authenticated run, issue, assigned connection, and accepted requester identity. A task tool must not fall back to a connection owner's credentials or an unrelated external conversation.
- Keep search scopes and counts aligned with the records returned by artifact, document, and connector views. A scope that counts a record but cannot open its result creates a silent navigation break.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A document update uses an old base revision | The update is rejected instead of silently replacing another edit | Require the current revision when writing and remap open annotations after a successful revision change |
| A write targets a locked document | The write fails or moves to a new document instead of changing the protected body | Treat the lock as authoritative and follow the returned replacement key when the create-new strategy is used |
| A selected annotation no longer matches the current document | The new thread is not created, or an existing thread becomes stale or orphaned | Verify the current revision before creation and keep anchor state visible during remap |
| An external provider needs auth or cannot be reached | The object can show stale or unavailable state instead of current remote status | Store liveness and retry information separately from the last known status |
| A workspace path leaves the workspace or names a denied segment | File preview, listing, or download is blocked | Normalize relative paths, resolve real paths inside the workspace root, and apply secret/path denial rules to every access mode |
| A provider webhook is unsigned, belongs to another bot account, or arrives for a paused endpoint | Paperclip does not admit a new task or message into the collaboration record | Verify the provider identity before callback handling and acknowledge paused or foreign traffic without mutation |
| An inbound delivery has no task binding | The system cannot safely replay it because replay could create work in the wrong issue | Bind the delivery to a conversation and issue before allowing replay |
| A provider reply has an unknown delivery result | Retrying can create a duplicate external message or duplicate file transfer | Show the action in connector activity and require mark-delivered, retry, or cancel resolution |
| A Slack search callback returns a different user, workspace, or app revision | The search grant can attach to the wrong identity or to stale app settings | Check the linked Paperclip identity, workspace, configuration revision, and allowed search scopes before storing the grant |
| An agent calls a Slack tool without a current task binding or assigned resource | The agent could read or act through an unrelated Slack connection | Require an authenticated run and recheck the issue, agent assignment, linked requester, and endpoint before execution |
| A board message is retried with the same request key | The same comment or publication is not created twice | Scope the idempotency key to the endpoint and conversation and retain the durable result |
| A selected attachment is already bound to another comment | The board send is rejected without publishing a partial message | Keep the rejection receipt and require a fresh attachment selection |
| A company search result matches a comment or document but its source is deleted | The result can point to missing context or fail to explain the match | Build snippets and links from visible current records and preserve the issue as the result anchor |
Key files
| File | Why to read it |
|---|---|
| server/…/company-artifacts.ts | Defines the company view that unifies documents, work-product outputs, and direct attachments. |
| ui/…/Artifacts.tsx | Shows how people browse, filter, group, and open produced work. |
| server/…/documents.ts | Defines the document lifecycle, revision expectations, and behavior for locked documents. |
| server/…/issues.ts | Defines durable issue comments, authorship, attachments, and activity impact. |
| server/…/board-chat.ts | Shows how board conversation becomes a persistent issue record. |
| server/…/chat-channels.ts | Shows the access boundary for provider conversations, activity, publication, replay, and inbound webhooks. |
| server/…/chat-channels.ts | Defines the durable relationship between external provider events, Paperclip conversations, issues, publications, resources, and connector activity. |
| server/…/slack-tools.ts | Shows the user flow for Slack search access and the run-bound route for Slack agent tools. |
| server/…/slack-search-oauth.ts | Defines the user-scoped Slack search grant, identity checks, refresh rules, and disconnect behavior. |
| server/…/connector-runtime.ts | Shows how assigned connector resources and tools are exposed to an agent run and checked again at call time. |
| server/…/document-annotations.ts | Defines anchored review threads and their relationship to document revisions. |
| server/…/external-objects.ts | Defines recognition, grouping, refresh, and status for linked outside objects. |
| server/…/workspace-file-resources.ts | Defines workspace file discovery, safety boundaries, previews, and availability. |
| server/…/company-search.ts | Defines cross-record search scopes, snippets, ranking, and counts. |
| ui/…/IssueChatThread.tsx | Shows the unified issue conversation view for comments, runs, tools, and live state. |
| ui/…/DocumentAnnotationPanel.tsx | Shows the user-facing review panel for anchored document discussions. |