Files
PaperClipAI/maps/agent-access-map
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
..
…
…
…
…
…
…
…
…

Paperclip agent access map

This map accompanies the feature map. It records APIs, agent entry points, permission boundaries and verification for the same capability IDs. The shared contract defines the format and maintenance rules.

The chat scenario catalog uses these same IDs for human requests and expected outcomes. Its scenarios retain the access boundaries here; neither a CEO role nor a planned scenario grants board authority or establishes a working production tool binding.

Use full capability IDs when referring to access contracts outside their file: onboarding/company means the company capability in onboarding.md in both maps. The feature index lists feature and capability IDs; IDs and references explains entry-point references and stable naming.

Browse access contracts

The same-named feature recipes define navigation and capability IDs. Run node scripts/storybook-catalog.mjs for the generated maps/generated/agent-access-map.md index, or browse the published feature guide. Add or update the affected companion; there is no central registration or count.

Existing baseline source references describe the original inspection, not current verification. Record new executed evidence in the PR, issue, or CI artifact with its revision and scope. Do not refresh unrelated headers as bookkeeping.

Using an entry

Read its Policy and Gaps before selecting an agent path. Native fallback, legacy REST/CLI, stdio MCP and a personal assistant connection can have different authority and availability. Use a real admitted production binding; a scenario declaration is not an installed tool. A restricted entry records current enforcement and leaves any unresolved delegation decision visible.

For API catalog disagreements, follow the route/service authorization and record discovery drift. For not-applicable, retain the concrete exception and local path. Split shared business operations from client-only presentation.

Use maintain-verification-skill to reconcile changed source and both maps. Use verify-paperclip and existing API/runner/MCP fixtures to collect the permitted-agent and denial evidence; report blocked/not-run coverage honestly. Run node scripts/check-maps.mjs after editing. The structural check does not certify permissions, API catalog coverage, tool admission or live behavior.

Native REST transport

The call_api parity change reconciles affected baselines against 58e16dbddfc9c8d0cf60867f9d9847f0feda055b and the changes in this PR. Ordinary REST operations use the same route authorization as legacy agent REST. Dedicated tools remain optional for those operations; protocol endpoints still need their existing clients. Board-only routes remain restricted for agent identity.

Native search_api / call_api is enabled by default, but explicit server, company-allowlist and binding settings can narrow admission. It requires a running authorized native run, current task assignment and execution-run binding, company and budget authority, task privacy, and a permitted work mode. Ask and Plan retain mutation restrictions, and runs retain their admitted JWT scope during restart recovery even when task mode changes. A waiting agent does not gain independent native control just because a REST route exists. Connection-management reads support Standard, Ask and Plan; mutations require Standard. Skill-test runs and nonstandard task-bridge keys cannot administer connections. These gates supplement each operation's grants, resolved resource and target scope, and responsible-user authority. See the rollout policy and connection authorization.

Credential-bearing replies, including company exports and their legacy alias, stay inline under a 10 MiB limit and use encrypted mutation receipts. Other saved API snapshots are limited to the issuing actor and responsible user, plus authorized administrators. Artifact uploads enforce the same access checks as downloads; private snapshots are excluded from company exports and public company logos. Explicit deliverables use the existing sharing path. Native event history, checkpoints and completion records omit API bodies while preserving receipt metadata and replay digests. Restored webhook secrets use the same encrypted receipt and inline response policy as newly created webhook secrets. Task image access requires the company boundary and the task permission; skill-test and low-trust agents do not need company-wide browsing authority. Completion replay applies the same idempotent projection to stored and expected payloads; the run-log guide describes its fields.

Sources: API client, catalog, native authority, credential storage classification, snapshot access, and history redaction. The affected entries remain baseline and source-only; this reconciliation does not certify every operation. Targeted real-route proof lives in the API integration suite, including owned routines, skill tests, scoped secrets, proposals and private export replay.