Files
PaperClipAI/doc/integration-api-notes.md
T
DottaandClaude Fable 5.2 ac114d9479 refactor: cut DEVELOPING.md to a setup and workflow guide (#21670)
## 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>
2026-11-14 18:02:27 -06:00

3.2 KiB

Integration API notes

Small API contracts that integrations and agents rely on.

Task document bodies

The native write_document tool preserves the supplied Markdown body, including leading whitespace, hard-break spaces, line endings, and final newlines. It still requires a nonblank body and normalizes key/title fields. write_task_document and REST document PUT also retain surrounding whitespace. Those REST-backed paths keep their existing escaped-line-break normalization: a body with no real line breaks can have literal \n sequences converted to newlines.

Starting a prepared task

An integration can create a task in backlog, save its initial documents, and then promote it with PATCH /api/issues/{id}. Send exactly { "status": "todo", "expectedStatusVersion": N }, using the statusVersion from the task whose initialization the integration owns. Capture that version on a server that already advertises this guard, before preparing the task. Older servers did not track every assignment path; reconcile older initialization intents instead of promoting them automatically after an upgrade. The server checks the version and backlog state under the task row lock. A status or assignment change returns 409 with details.code: "issue_status_version_changed"; mixed mutation fields return 422. The guard is optional and applies only to this promotion. It does not provide a general conditional lifecycle or execution-control API. Assignment changes advance the revision at the database boundary, including release, administrative release, and direct service writes. A no-op assignment keeps the revision. Migration 0358 adds this trigger without rewriting tasks.

Persist the original version with the integration's initialization intent so a later retry cannot override a person's intervening decision. A caller still needs the ordinary company, task, assignment and run permissions. Do not retry an uncertain write until the saved task and initialization state are reconciled.

Agent Invite Onboarding Endpoints

Agent-oriented invite onboarding now exposes machine-readable API docs:

The board UI generates agent onboarding prompts from the add-agent modal (+ in the agent sidebar), so agent onboarding sits with the rest of agent creation rather than company member invite settings.

  • GET /api/invites/:token returns invite summary plus onboarding and skills index links.
  • GET /api/invites/:token/onboarding returns onboarding manifest details (registration endpoint, claim endpoint template, skill install hints).
  • GET /api/invites/:token/onboarding.txt returns a plain-text onboarding doc intended for both human operators and agents (llm.txt-style handoff), including optional inviter message and suggested network host candidates.
  • GET /api/skills/index lists available skill documents.
  • GET /api/skills/paperclip returns the Paperclip heartbeat skill markdown.

Hermes gateway agents use this same generic agent invite flow with adapterType=hermes_gateway and agentDefaultsPayload.apiBaseUrl / agentDefaultsPayload.apiKey. See HERMES_GATEWAY_ONBOARDING.md for the full operator path, including Hermes credentials, invite approval, key claim, and fresh-state Docker smoke setup.