## 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>
5.8 KiB
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 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 for the gates,
recovery behavior, and production-component stories.