mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 21:34:48 +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>
94 lines
5.8 KiB
Markdown
94 lines
5.8 KiB
Markdown
# Chat connector development
|
||
|
||
Setting up Slack chat against a local instance, and connector diagnostics.
|
||
|
||
## Slack chat setup in a test drive
|
||
|
||
Enable **Chat connectors** in Instance Settings, then open **Connectors → Slack →
|
||
Chat with an agent**. Before creating an app, configure a public HTTPS board URL
|
||
and webhook ingress that Slack can reach. The setup page shows this prerequisite;
|
||
a loopback test drive can exercise the UI before HTTPS is configured.
|
||
|
||
New Slack connections use five steps: choose an agent, enter an app configuration
|
||
token, install the app, verify Slack delivery, and try a conversation. Agent
|
||
selection generates readable defaults for the Slack app name, bot display name,
|
||
and slash command; edit them under **Advanced** if needed. **Get your App
|
||
configuration token** opens Slack app settings. Enter the temporary token directly
|
||
into Paperclip, then select **Create Slack app**. Paperclip creates the app,
|
||
vaults its credentials, and attempts avatar upload before discarding the token.
|
||
App details lock after creation dispatch, including an uncertain result.
|
||
|
||
**Install in Slack** obtains the bot token through OAuth, links the installing
|
||
Slack account to the Paperclip account that started installation, and sends one
|
||
welcome DM. Approve with your own Slack account. After Slack verifies the Events
|
||
Request URL, use **Open your Slack DM**, send the suggested message, and continue
|
||
in the thread. **Done** finishes setup; the conversation test is optional.
|
||
See [Automatic Slack app setup](connections/SLACK-AUTOMATIC-SETUP.md) for
|
||
HTTPS configuration and recovery.
|
||
|
||
**Create manually** and **Use an existing app** are under **Advanced** on the
|
||
token step. These paths retain manual credential entry and a separate personal
|
||
account-linking step. Send `/<your-command> connect` to discover your identity
|
||
without starting work, then confirm **This is my Slack account** in the wizard
|
||
or use the private confirmation link. The link expires after 15 minutes and
|
||
requires company membership. Future messages use the linked user's current
|
||
permissions. Additional or different accounts can be linked later in **Access**.
|
||
|
||
New Slack connections disable **Allow unlinked people** by default. The Access
|
||
page includes the shareable connect command and instructions for other users.
|
||
Other Slack users join through the same connect command after setup. A signed-in
|
||
nonmember can **Request access** from the confirmation page. This creates a
|
||
pending human join request in the company's existing admin approval queue; it
|
||
does not grant membership or link the identity. After approval, confirm the
|
||
identity, or send the connect command again if the link has expired. Successful
|
||
confirmation also queues a private Slack acknowledgement.
|
||
|
||
Slack identity invitation pages retain the cloud authentication and bootstrap
|
||
checks. Signed-in nonmembers may open a valid private invitation to request
|
||
membership, but confirmation still requires membership in the invitation's
|
||
company. Preview, access-request, and confirmation APIs also enforce the chat
|
||
connector rollout flag on the server; invitees cannot read board experimental
|
||
settings before they join. Expired or consumed tokens grant no access.
|
||
|
||
The manual path suggests `@<your-bot> you there?`, then continuing in the agent's
|
||
thread. Select the bot from Slack's @mention suggestions so the message includes
|
||
a real mention. **Done** finishes setup once webhook verification and required
|
||
account linking are complete, whether or not a test message was sent. The
|
||
separate strict connection-test API retains its conversation and delivery checks.
|
||
|
||
New Slack conversations receive default communication guidance that requires a
|
||
clickable link to each task the agent creates. Agents use the public task URL
|
||
from Paperclip tools or task context and report when a link is unavailable.
|
||
Existing conversations keep their original communication guidance snapshot.
|
||
|
||
Slack catalog discovery uses `resolveSlackTaskAuthorization` to recheck the live
|
||
run, task, agent, linked user, endpoint, and current bot credential. Discovery
|
||
does not consume a compatibility revision, so it avoids hashing company policy
|
||
and profile rows. Callers that need a revision continue to use
|
||
`resolveSlackTaskAuthority`; connector skill snapshots and governed operations
|
||
retain their existing fingerprint. Both paths share the same authorization
|
||
implementation and perform fresh checks on every call. The real PostgreSQL
|
||
controls are in `server/src/__tests__/slack-tool-preparation.test.ts`.
|
||
|
||
## Chat activity pagination and callback diagnostics
|
||
|
||
The connection Activity tab loads 25 records per page. `GET /api/chat-endpoints/:id/activity?limit=25`
|
||
returns `{ items, nextCursor }`; pass `cursor` to read older records. The limit must be 1–100.
|
||
A timestamp and ID cursor preserves records with equal timestamps and avoids shifts from new arrivals.
|
||
The first page refreshes automatically; older pages do not poll. Mutable action status can move an
|
||
entry forward in time, so this is a live ledger, not a historical snapshot. Requests without pagination
|
||
parameters retain the recent-100 array response for existing clients.
|
||
|
||
Slack callback diagnostics tolerate HTTP between a TLS proxy and Paperclip when the public host,
|
||
port, and path still match. A changed authority or path remains stale. This comparison only affects
|
||
health display; it does not trust forwarded headers or alter Slack signature verification.
|
||
|
||
## Slack provisioning paths
|
||
|
||
Self-hosted development continues to use independent Slack app setup. Managed
|
||
Slack installation is a disabled-by-default Cloud feature that also requires the
|
||
companion broker profile and Slack approval. Do not add manager client credentials
|
||
to a local `.env` or an open-source deployment. See
|
||
[Slack setup and Cloud qualification](connections/slack-setup.md) for the gates,
|
||
recovery behavior, and production-component stories.
|